1. Administration Guide
    1. About This Guide
    2. I Common Tasks
    3. II Booting a Linux System
    4. III System
    5. IV Services
    6. V Mobile Computers
    7. VI Troubleshooting
    8. A Documentation Updates
    9. B An Example Network
    10. C GNU Licenses
  2. Deployment Guide
    1. About This Guide
    2. 1 Planning for SUSE Linux Enterprise Server
    3. I Installation Preparation
    4. II The Installation Workflow
    5. III Setting Up an Installation Server
    6. IV Remote Installation
    7. V Initial System Configuration
    8. VI Updating and Upgrading SUSE Linux Enterprise
    9. A Documentation Updates
    10. B GNU Licenses
  3. GNOME User Guide
    1. About This Guide
    2. I Introduction
    3. II Connectivity, Files and Resources
    4. III LibreOffice
    5. IV Internet, Communication and Collaboration
    6. V Graphics and Multimedia
    7. A Help and Documentation
    8. B Documentation Updates
    9. C GNU Licenses
  4. AutoYaST
    1. 1 Introduction
    2. 2 The Control File
    3. 3 Creating A Control File
    4. 4 Configuration and Installation Options
    5. 5 Rules and Classes
    6. 6 The Auto-Installation Process
    7. 7 Running AutoYaST in an Installed System
    8. A Handling Rules
    9. B AutoYaST FAQ - Frequently Asked Questions
    10. C Advanced Linuxrc Options
    11. D Documentation Updates
    12. E GNU Licenses
  5. Security Guide
    1. About This Guide
    2. 1 Security and Confidentiality
    3. I Authentication
    4. II Local Security
    5. III Network Security
    6. IV Confining Privileges with AppArmor
    7. V SELinux
    8. VI The Linux Audit Framework
    9. A Achieving PCI-DSS Compliance
    10. B Documentation Updates
    11. C GNU Licenses
  6. System Analysis and Tuning Guide
    1. About This Guide
    2. I Basics
    3. II System Monitoring
    4. III Kernel Monitoring
    5. IV Resource Management
    6. V Kernel Tuning
    7. VI Handling System Dumps
    8. VII Synchronized Clocks with Precision Time Protocol
    9. A Documentation Updates
    10. B GNU Licenses
  7. SMT Guide
    1. About This Guide
    2. 1 SMT Installation
    3. 2 SMT Server Configuration
    4. 3 Mirroring Repositories on the SMT Server
    5. 4 Managing Repositories with YaST SMT Server Management
    6. 5 Managing Client Machines with SMT
    7. 6 SMT Reports
    8. 7 SMT Tools and Configuration Files
    9. 8 Configuring Clients to Use SMT
    10. 9 Advanced Topics
    11. A SMT REST API
    12. B Documentation Updates
  8. Storage Administration Guide
    1. About This Guide
    2. I File Systems and Mounting
    3. II Logical Volumes (LVM)
    4. III Software RAID
    5. IV Network Storage
    6. A Documentation Updates
    7. B GNU Licenses
  9. Security and Hardening Guide
    1. About This Guide
    2. I Common Criteria
    3. II General System Security and Service Protection Methods
    4. A Documentation Updates
  10. Virtualization Guide
    1. About This Manual
    2. I Introduction
    3. II Managing Virtual Machines with libvirt
    4. III Hypervisor-Independent Features
    5. IV Managing Virtual Machines with Xen
    6. V Managing Virtual Machines with QEMU
    7. VI Managing Virtual Machines with LXC
    8. Glossary
    9. A Virtual Machine Drivers
    10. B Appendix
    11. C XM, XL Toolstacks and Libvirt framework
    12. D Documentation Updates
    13. E GNU Licenses
  11. Docker Guide
    1. 1 Docker Overview
    2. 2 Docker Installation
    3. 3 Installing sle2docker
    4. 4 Storing Images
    5. 5 Creating Custom Images
    6. 6 Dockerizing Applications
    7. 7 Working with Containers
    8. A Documentation Updates
    9. B GNU Licenses
  12. Quick Start Manuals
    1. Installation Quick Start
    2. Xen to KVM Migration Guide
    3. Virtualization Best Practices
    4. A GNU Licenses
SUSE Linux Enterprise Server 12 SP3

SUSE Linux Enterprise Server Documentation

SUSE Linux Enterprise Server 12 SP3

Administration Guide

Covers system administration tasks like maintaining, monitoring and customizing an initially installed system.

Publication Date: April 04, 2018
About This Guide
Available Documentation
Feedback
Documentation Conventions
About the Making of This Documentation
I Common Tasks
1 Bash and Bash Scripts
1.1 What is The Shell?
1.2 Writing Shell Scripts
1.3 Redirecting Command Events
1.4 Using Aliases
1.5 Using Variables in Bash
1.6 Grouping and Combining Commands
1.7 Working with Common Flow Constructs
1.8 For More Information
2 sudo
2.1 Basic sudo Usage
2.2 Configuring sudo
2.3 Common Use Cases
2.4 More Information
3 YaST Online Update
3.1 The Online Update Dialog
3.2 Installing Patches
3.3 Automatic Online Update
4 YaST
4.1 Advanced Key Combinations
5 YaST in Text Mode
5.1 Navigation in Modules
5.2 Advanced Key Combinations
5.3 Restriction of Key Combinations
5.4 YaST Command Line Options
6 Managing Software with Command Line Tools
6.1 Using Zypper
6.2 RPM—the Package Manager
7 System Recovery and Snapshot Management with Snapper
7.1 Default Setup
7.2 Using Snapper to Undo Changes
7.3 System Rollback by Booting from Snapshots
7.4 Creating and Modifying Snapper Configurations
7.5 Manually Creating and Managing Snapshots
7.6 Automatic Snapshot Clean-Up
7.7 Frequently Asked Questions
8 Remote Access with VNC
8.1 The vncviewer Client
8.2 Remmina: the Remote Desktop Client
8.3 One-time VNC Sessions
8.4 Persistent VNC Sessions
8.5 Encrypted VNC Communication
9 File Copying with RSync
9.1 Conceptual Overview
9.2 Basic Syntax
9.3 Copying Files and Directories Locally
9.4 Copying Files and Directories Remotely
9.5 Configuring and Using an Rsync Server
9.6 For More Information
II Booting a Linux System
10 Introduction to the Booting Process
10.1 The Linux Boot Process
10.2 initramfs
10.3 Init on initramfs
11 UEFI (Unified Extensible Firmware Interface)
11.1 Secure Boot
11.2 For More Information
12 The Boot Loader GRUB 2
12.1 Main Differences between GRUB Legacy and GRUB 2
12.2 Configuration File Structure
12.3 Configuring the Boot Loader with YaST
12.4 Differences in Terminal Usage on z Systems
12.5 Helpful GRUB 2 Commands
12.6 More Information
13 The systemd Daemon
13.1 The systemd Concept
13.2 Basic Usage
13.3 System Start and Target Management
13.4 Managing Services with YaST
13.5 Customization of systemd
13.6 Advanced Usage
13.7 More Information
III System
14 32-Bit and 64-Bit Applications in a 64-Bit System Environment
14.1 Runtime Support
14.2 Software Development
14.3 Software Compilation on Biarch Platforms
14.4 Kernel Specifications
15 journalctl: Query the systemd Journal
15.1 Making the Journal Persistent
15.2 journalctl Useful Switches
15.3 Filtering the Journal Output
15.4 Investigating systemd Errors
15.5 Journald Configuration
15.6 Using YaST to Filter the systemd Journal
16 Basic Networking
16.1 IP Addresses and Routing
16.2 IPv6—The Next Generation Internet
16.3 Name Resolution
16.4 Configuring a Network Connection with YaST
16.5 Configuring a Network Connection Manually
16.6 Basic Router Setup
16.7 Setting Up Bonding Devices
16.8 Setting Up Team Devices for Network Teaming
16.9 Software-Defined Networking with Open vSwitch
17 Printer Operation
17.1 The CUPS Workflow
17.2 Methods and Protocols for Connecting Printers
17.3 Installing the Software
17.4 Network Printers
17.5 Configuring CUPS with Command Line Tools
17.6 Printing from the Command Line
17.7 Special Features in SUSE Linux Enterprise Server
17.8 Troubleshooting
18 The X Window System
18.1 Installing and Configuring Fonts
18.2 For More Information
19 Accessing File Systems with FUSE
19.1 Configuring FUSE
19.2 Mounting an NTFS Partition
19.3 For More Information
20 Managing Kernel Modules
20.1 Listing Loaded Modules with lsmod and modinfo
20.2 Adding and Removing Kernel Modules
21 Dynamic Kernel Device Management with udev
21.1 The /dev Directory
21.2 Kernel uevents and udev
21.3 Drivers, Kernel Modules and Devices
21.4 Booting and Initial Device Setup
21.5 Monitoring the Running udev Daemon
21.6 Influencing Kernel Device Event Handling with udev Rules
21.7 Persistent Device Naming
21.8 Files used by udev
21.9 For More Information
22 Live Patching the Linux Kernel Using kGraft
22.1 Advantages of kGraft
22.2 Low-level Function of kGraft
22.3 Installing kGraft Patches
22.4 Patch Lifecycle
22.5 Removing a kGraft Patch
22.6 Stuck Kernel Execution Threads
22.7 The kgr Tool
22.8 Scope of kGraft Technology
22.9 Scope of SLE Live Patching
22.10 Interaction with the Support Processes
23 Special System Features
23.1 Information about Special Software Packages
23.2 Virtual Consoles
23.3 Keyboard Mapping
23.4 Language and Country-Specific Settings
IV Services
24 Time Synchronization with NTP
24.1 Configuring an NTP Client with YaST
24.2 Manually Configuring NTP in the Network
24.3 Dynamic Time Synchronization at Runtime
24.4 Setting Up a Local Reference Clock
24.5 Clock Synchronization to an External Time Reference (ETR)
25 The Domain Name System
25.1 DNS Terminology
25.2 Installation
25.3 Configuration with YaST
25.4 Starting the BIND Name Server
25.5 The /etc/named.conf Configuration File
25.6 Zone Files
25.7 Dynamic Update of Zone Data
25.8 Secure Transactions
25.9 DNS Security
25.10 For More Information
26 DHCP
26.1 Configuring a DHCP Server with YaST
26.2 DHCP Software Packages
26.3 The DHCP Server dhcpd
26.4 For More Information
27 Sharing File Systems with NFS
27.1 Terminology
27.2 Installing NFS Server
27.3 Configuring NFS Server
27.4 Configuring Clients
27.5 For More Information
28 Samba
28.1 Terminology
28.2 Installing a Samba Server
28.3 Starting and Stopping Samba
28.4 Configuring a Samba Server
28.5 Configuring Clients
28.6 Samba as Login Server
28.7 Samba Server in the Network with Active Directory
28.8 Advanced Topics
28.9 For More Information
29 On-Demand Mounting with Autofs
29.1 Installation
29.2 Configuration
29.3 Operation and Debugging
29.4 Auto-Mounting an NFS Share
29.5 Advanced Topics
30 SLP
30.1 The SLP Front-End slptool
30.2 Providing Services via SLP
30.3 For More Information
31 The Apache HTTP Server
31.1 Quick Start
31.2 Configuring Apache
31.3 Starting and Stopping Apache
31.4 Installing, Activating, and Configuring Modules
31.5 Enabling CGI Scripts
31.6 Setting Up a Secure Web Server with SSL
31.7 Running Multiple Apache Instances on the Same Server
31.8 Avoiding Security Problems
31.9 Troubleshooting
31.10 For More Information
32 Setting Up an FTP Server with YaST
32.1 Starting the FTP Server
32.2 FTP General Settings
32.3 FTP Performance Settings
32.4 Authentication
32.5 Expert Settings
32.6 For More Information
33 The Proxy Server Squid
33.1 Some Facts about Proxy Caches
33.2 System Requirements
33.3 Basic Usage of Squid
33.4 The YaST Squid Module
33.5 The Squid Configuration File
33.6 Configuring a Transparent Proxy
33.7 Using the Squid Cache Manager CGI Interface (cachemgr.cgi)
33.8 squidGuard
33.9 Cache Report Generation with Calamaris
33.10 For More Information
34 Web Based Enterprise Management Using SFCB
34.1 Introduction and Basic Concept
34.2 Setting Up SFCB
34.3 SFCB CIMOM Configuration
34.4 Advanced SFCB Tasks
34.5 For More Information
V Mobile Computers
35 Mobile Computing with Linux
35.1 Laptops
35.2 Mobile Hardware
35.3 Cellular Phones and PDAs
35.4 For More Information
36 Using NetworkManager
36.1 Use Cases for NetworkManager
36.2 Enabling or Disabling NetworkManager
36.3 Configuring Network Connections
36.4 NetworkManager and Security
36.5 Frequently Asked Questions
36.6 Troubleshooting
36.7 For More Information
37 Power Management
37.1 Power Saving Functions
37.2 Advanced Configuration and Power Interface (ACPI)
37.3 Rest for the Hard Disk
37.4 Troubleshooting
37.5 For More Information
VI Troubleshooting
38 Help and Documentation
38.1 Documentation Directory
38.2 Man Pages
38.3 Info Pages
38.4 Online Resources
39 Gathering System Information for Support
39.1 Displaying Current System Information
39.2 Collecting System Information with Supportconfig
39.3 Submitting Information to Global Technical Support
39.4 Analyzing System Information
39.5 Gathering Information during the Installation
39.6 Support of Kernel Modules
39.7 For More Information
40 Common Problems and Their Solutions
40.1 Finding and Gathering Information
40.2 Installation Problems
40.3 Boot Problems
40.4 Login Problems
40.5 Network Problems
40.6 Data Problems
40.7 IBM z Systems: Using initrd as a Rescue System
A Documentation Updates
A.1 January 2018 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)
A.2 December 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)
A.3 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)
A.4 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)
A.5 March 2016 (Maintenance Release of SUSE Linux Enterprise Server 12 SP1)
A.6 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)
A.7 February 2015 (Documentation Maintenance Update)
A.8 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)
B An Example Network
C GNU Licenses
C.1 GNU Free Documentation License
List of Figures
3.1 YaST Online Update
5.1 Main Window of YaST in Text Mode
5.2 The Software Installation Module
7.1 Boot Loader: Snapshots
8.1 vncviewer
8.2 Remmina's Main Window
8.3 Remote Desktop Preference
8.4 Quick-starting
8.5 Remmina Viewing SLES 15 Remote Session
8.6 Reading Path to the Profile File
8.7 Remote Administration
8.8 VNC Session Settings
8.9 Joining a Persistent VNC Session
11.1 Secure Boot Support
11.2 UEFI: Secure Boot Process
12.1 GRUB 2 Boot Editor
12.2 Boot Code Options
12.3 Code Options
12.4 Boot loader Options
12.5 Kernel Parameters
13.1 Services Manager
15.1 YaST systemd Journal
16.1 Simplified Layer Model for TCP/IP
16.2 TCP/IP Ethernet Packet
16.3 Configuring Network Settings
16.4 wicked architecture
24.1 YaST: NTP Server
24.2 Advanced NTP Configuration: Security Settings
25.1 DNS Server Installation: Forwarder Settings
25.2 DNS Server Installation: DNS Zones
25.3 DNS Server Installation: Finish Wizard
25.4 DNS Server: Logging
25.5 DNS Server: Zone Editor (Basics)
25.6 DNS Server: Zone Editor (NS Records)
25.7 DNS Server: Zone Editor (MX Records)
25.8 DNS Server: Zone Editor (SOA)
25.9 Adding a Record for a Master Zone
25.10 Adding a Reverse Zone
25.11 Adding a Reverse Record
26.1 DHCP Server: Card Selection
26.2 DHCP Server: Global Settings
26.3 DHCP Server: Dynamic DHCP
26.4 DHCP Server: Start-Up
26.5 DHCP Server: Host Management
26.6 DHCP Server: Chroot Jail and Declarations
26.7 DHCP Server: Selecting a Declaration Type
26.8 DHCP Server: Configuring Subnets
26.9 DHCP Server: TSIG Configuration
26.10 DHCP Server: Interface Configuration for Dynamic DNS
26.11 DHCP Server: Network Interface and Firewall
27.1 NFS Server Configuration Tool
28.1 Determining Windows Domain Membership
28.2 Windows Explorer Advanced Attributes Dialog
28.3 Windows Explorer Directory Listing with Compressed Files
28.4 Adding a New Samba Share with Snapshotting Enabled
28.5 The Previous Versions tab in Windows Explorer
31.1 HTTP Server Wizard: Default Host
31.2 HTTP Server Wizard: Summary
31.3 HTTP Server Configuration: Listen Ports and Addresses
31.4 HTTP Server Configuration: Server Modules
32.1 FTP Server Configuration — Start-Up
34.1 Package Selection for Web-Based Enterprise Management Pattern
34.2 Package selection of additional CIM providers
35.1 Integrating a Mobile Computer in an Existing Environment
36.1 GNOME Network Connections Dialog
39.1 HTML Report Generated by SCA Tool
39.2 HTML Report Generated by SCA Appliance
40.1 Checking Media
40.2 US Keyboard Layout
List of Examples
1.1 A Shell Script Printing a Text
6.1 Zypper—List of Known Repositories
6.2 rpm -q -i wget
6.3 Script to Search for Packages
7.1 Example timeline configuration
12.1 Usage of grub2-mkconfig
12.2 Usage of grub2-mkrescue
12.3 Usage of grub2-script-check
12.4 Usage of grub2-once
13.1 List Active Services
13.2 List Failed Services
13.3 List all Processes Belonging to a Service
16.1 Writing IP Addresses
16.2 Linking IP Addresses to the Netmask
16.3 Sample IPv6 Address
16.4 IPv6 Address Specifying the Prefix Length
16.5 Common Network Interfaces and Some Static Routes
16.6 /etc/resolv.conf
16.7 /etc/hosts
16.8 /etc/networks
16.9 /etc/host.conf
16.10 /etc/nsswitch.conf
16.11 Output of the Command ping
16.12 Configuration for Loadbalancing with Network Teaming
16.13 Configuration for DHCP Network Teaming Device
17.1 Error Message from lpd
17.2 Broadcast from the CUPS Network Server
18.1 Specifying Rendering Algorithms
18.2 Aliases and Family Name Substitutions
18.3 Aliases and Family Name Substitutions
18.4 Aliases and Family Names Substitutions
21.1 Example udev Rules
23.1 Entry in /etc/crontab
23.2 /etc/crontab: Remove Time Stamp Files
23.3 ulimit: Settings in ~/.bashrc
25.1 Forwarding Options in named.conf
25.2 A Basic /etc/named.conf
25.3 Entry to Disable Logging
25.4 Zone Entry for example.com
25.5 Zone Entry for example.net
25.6 The /var/lib/named/example.com.zone File
25.7 Reverse Lookup
26.1 The Configuration File /etc/dhcpd.conf
26.2 Additions to the Configuration File
28.1 A CD-ROM Share
28.2 [homes] Share
28.3 Global Section in smb.conf
28.4 Using rpcclient to Request a Windows Server 2012 Share Snapshot
31.1 Basic Examples of Name-Based VirtualHost Entries
31.2 Name-Based VirtualHost Directives
31.3 IP-Based VirtualHost Directives
31.4 Basic VirtualHost Configuration
31.5 VirtualHost CGI Configuration
33.1 A Request With squidclient
33.2 Defining ACL Rules
39.1 Output of hostinfo When Logging In as root

Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

About This Guide

  • Filename: sle_admin_intro.xml
  • ID: pre.sle

This guide is intended for use by professional network and system administrators during the operation of SUSE® Linux Enterprise. As such, it is solely concerned with ensuring that SUSE Linux Enterprise is properly configured and that the required services on the network are available to allow it to function properly as initially installed. This guide does not cover the process of ensuring that SUSE Linux Enterprise offers proper compatibility with your enterprise's application software or that its core functionality meets those requirements. It assumes that a full requirements audit has been done and the installation has been requested, or that a test installation for such an audit has been requested.

This guide contains the following:

Support and Common Tasks

SUSE Linux Enterprise offers a wide range of tools to customize various aspects of the system. This part introduces a few of them. A breakdown of available device technologies, high availability configurations, and advanced administration possibilities introduces the system to the administrator.

System

Learn more about the underlying operating system by studying this part. SUSE Linux Enterprise supports several hardware architectures and you can use this to adapt your own applications to run on SUSE Linux Enterprise. The boot loader and boot procedure information assists you in understanding how your Linux system works and how your own custom scripts and applications may blend in with it.

Services

SUSE Linux Enterprise is designed to be a network operating system. It offers a wide range of network services, such as DNS, DHCP, Web, proxy, and authentication services. It also integrates well into heterogeneous environments, including MS Windows clients and servers.

Mobile Computers

Laptops, and the communication between mobile devices like PDAs, or cellular phones and SUSE Linux Enterprise need some special attention. Take care for power conservation and for the integration of different devices into a changing network environment. Also get in touch with the background technologies that provide the needed functionality.

Troubleshooting

Provides an overview of finding help and additional documentation when you need more information or want to perform specific tasks. There is also a list of the most frequent problems with explanations how to fix them.

1 Available Documentation

  • Filename: common_intro_available_doc_i.xml
  • ID: no ID found
Note
Note: Online Documentation and Latest Updates

Documentation for our products is available at http://www.suse.com/documentation/, where you can also find the latest updates, and browse or download the documentation in various formats.

In addition, the product documentation is usually available in your installed system under /usr/share/doc/manual.

The following documentation is available for this product:

Installation Quick Start

Lists the system requirements and guides you step-by-step through the installation of SUSE Linux Enterprise Server from DVD, or from an ISO image.

Deployment Guide

Shows how to install single or multiple systems and how to exploit the product inherent capabilities for a deployment infrastructure. Choose from various approaches, ranging from a local installation or a network installation server to a mass deployment using a remote-controlled, highly-customized, and automated installation technique.

Administration Guide

Covers system administration tasks like maintaining, monitoring and customizing an initially installed system.

Virtualization Guide

Describes virtualization technology in general, and introduces libvirt—the unified interface to virtualization—and detailed information on specific hypervisors.

Storage Administration Guide

Provides information about how to manage storage devices on a SUSE Linux Enterprise Server.

AutoYaST

AutoYaST is a system for unattended mass deployment SUSE Linux Enterprise Server systems using an AutoYaST profile containing installation and configuration data. The manual guides you through the basic steps of auto-installation: preparation, installation, and configuration.

Security Guide

Introduces basic concepts of system security, covering both local and network security aspects. Shows how to use the product inherent security software like AppArmor or the auditing system that reliably collects information about any security-relevant events.

Security and Hardening Guide

Deals with the particulars of installing and setting up a secure SUSE Linux Enterprise Server, and additional post-installation processes required to further secure and harden that installation. Supports the administrator with security-related choices and decisions.

System Analysis and Tuning Guide

An administrator's guide for problem detection, resolution and optimization. Find how to inspect and optimize your system by means of monitoring tools and how to efficiently manage resources. Also contains an overview of common problems and solutions and of additional help and documentation resources.

SMT Guide

An administrator's guide to Subscription Management Tool—a proxy system for SUSE Customer Center with repository and registration targets. Learn how to install and configure a local SMT server, mirror and manage repositories, manage client machines, and configure clients to use SMT.

GNOME User Guide

Introduces the GNOME desktop of SUSE Linux Enterprise Server. It guides you through using and configuring the desktop and helps you perform key tasks. It is intended mainly for end users who want to make efficient use of GNOME as their default desktop.

2 Feedback

  • Filename: common_intro_feedback_i.xml
  • ID: no ID found

Several feedback channels are available:

Bugs and Enhancement Requests

For services and support options available for your product, refer to http://www.suse.com/support/.

Help for openSUSE is provided by the community. Refer to https://en.opensuse.org/Portal:Support for more information.

To report bugs for a product component, go to https://scc.suse.com/support/requests, log in, and click Create New.

User Comments

We want to hear your comments about and suggestions for this manual and the other documentation included with this product. Use the User Comments feature at the bottom of each page in the online documentation or go to http://www.suse.com/documentation/feedback.html and enter your comments there.

Mail

For feedback on the documentation of this product, you can also send a mail to doc-team@suse.com. Make sure to include the document title, the product version and the publication date of the documentation. To report errors or suggest enhancements, provide a concise description of the problem and refer to the respective section number and page (or URL).

3 Documentation Conventions

  • Filename: common_intro_typografie_i.xml
  • ID: no ID found

The following notices and typographical conventions are used in this documentation:

  • /etc/passwd: directory names and file names

  • PLACEHOLDER: replace PLACEHOLDER with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • package name : name of a package

  • Alt, AltF1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File › Save As: menu items, buttons

  • x86_64 This paragraph is only relevant for the AMD64/Intel 64 architecture. The arrows mark the beginning and the end of the text block.

    System z, POWER This paragraph is only relevant for the architectures z Systems and POWER. The arrows mark the beginning and the end of the text block.

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

  • Commands that must be run with root privileges. Often you can also prefix these commands with the sudo command to run them as non-privileged user.

    root # command
    tux > sudo command
  • Commands that can be run by non-privileged users.

    tux > command
  • Notices

    Warning
    Warning: Warning Notice

    Vital information you must be aware of before proceeding. Warns you about security issues, potential loss of data, damage to hardware, or physical hazards.

    Important
    Important: Important Notice

    Important information you should be aware of before proceeding.

    Note
    Note: Note Notice

    Additional information, for example about differences in software versions.

    Tip
    Tip: Tip Notice

    Helpful information, like a guideline or a piece of practical advice.

4 About the Making of This Documentation

  • Filename: common_intro_making_i.xml
  • ID: no ID found

This documentation is written in SUSEDoc, a subset of DocBook 5. The XML source files were validated by jing (see https://code.google.com/p/jing-trang/), processed by xsltproc, and converted into XSL-FO using a customized version of Norman Walsh's stylesheets. The final PDF is formatted through FOP from Apache Software Foundation. The open source tools and the environment used to build this documentation are provided by the DocBook Authoring and Publishing Suite (DAPS). The project's home page can be found at https://github.com/openSUSE/daps.

The XML source code of this documentation can be found at https://github.com/SUSE/doc-sle.

Part I Common Tasks

1 Bash and Bash Scripts

Today, many people use computers with a graphical user interface (GUI) like GNOME. Although they offer lots of features, their use is limited when it comes to the execution of automated tasks. Shells are a good addition to GUIs and this chapter gives you an overview of some aspects of shells, in this case Bash.

2 sudo

Many commands and system utilities need to be run as root to modify files and/or perform tasks that only the super user is allowed to. For security reasons and to avoid accidentally running dangerous commands, it is generally advisable not to log in directly as root. Instead, it is recommended to wo…

3 YaST Online Update

SUSE offers a continuous stream of software security updates for your product. By default, the update applet is used to keep your system up-to-date. Refer to Section 13.5, “Keeping the System Up-to-date” for further information on the update applet. This chapter covers the alternative tool for updat…

4 YaST

YaST is the installation and configuration tool for SUSE Linux Enterprise Server. It has a graphical interface and the capability to customize your system quickly during and after the installation. It can be used to set up hardware, configure the network, system services, and tune your security sett…

5 YaST in Text Mode

This section is intended for system administrators and experts who do not run an X server on their systems and depend on the text-based installation tool. It provides basic information about starting and operating YaST in text mode.

6 Managing Software with Command Line Tools

This chapter describes Zypper and RPM, two command line tools for managing software. For a definition of the terminology used in this context (for example, repository, patch, or update) refer to Section 13.1, “Definition of Terms”.

7 System Recovery and Snapshot Management with Snapper

Being able to do file system snapshots providing the ability to do rollbacks on Linux is a feature that was often requested in the past. Snapper, with the Btrfs file system or thin-provisioned LVM volumes now fills that gap.

Btrfs, a new copy-on-write file system for Linux, supports file system snapshots (a copy of the state of a subvolume at a certain point of time) of subvolumes (one or more separately mountable file systems within each physical partition). Snapshots are also supported on thin-provisioned LVM volumes formatted with XFS, Ext4 or Ext3. Snapper lets you create and manage these snapshots. It comes with a command line and a YaST interface. Starting with SUSE Linux Enterprise Server 12 it is also possible to boot from Btrfs snapshots—see Section 7.3, “System Rollback by Booting from Snapshots” for more information.

8 Remote Access with VNC

Virtual Network Computing (VNC) enables you to control a remote computer via a graphical desktop (as opposed to a remote shell access). VNC is platform-independent and lets you access the remote machine from any operating system.

SUSE Linux Enterprise Server supports two different kinds of VNC sessions: One-time sessions that live as long as the VNC connection from the client is kept up, and persistent sessions that live until they are explicitly terminated.

9 File Copying with RSync

Today, a typical user has several computers: home and workplace machines, a laptop, a smartphone or a tablet. This makes the task of keeping files and documents in sync across multiple devices all more important.

1 Bash and Bash Scripts

  • Filename: adm_shell.xml
  • ID: cha.adm.shell
Abstract

Today, many people use computers with a graphical user interface (GUI) like GNOME. Although they offer lots of features, their use is limited when it comes to the execution of automated tasks. Shells are a good addition to GUIs and this chapter gives you an overview of some aspects of shells, in this case Bash.

1.1 What is The Shell?

Traditionally, the shell is Bash (Bourne again Shell). When this chapter speaks about the shell it means Bash. There are actually more available shells than Bash (ash, csh, ksh, zsh, …), each employing different features and characteristics. If you need further information about other shells, search for shell in YaST.

1.1.1 Knowing the Bash Configuration Files

A shell can be invoked as an:

  1. Interactive login shell.  This is used when logging in to a machine, invoking Bash with the --login option or when logging in to a remote machine with SSH.

  2. Ordinary interactive shell.  This is normally the case when starting xterm, konsole, gnome-terminal or similar tools.

  3. Non-interactive shell.  This is used when invoking a shell script at the command line.

Depending on which type of shell you use, different configuration files are being read. The following tables show the login and non-login shell configuration files.

Table 1.1: Bash Configuration Files for Login Shells

File

Description

/etc/profile

Do not modify this file, otherwise your modifications can be destroyed during your next update!

/etc/profile.local

Use this file if you extend /etc/profile

/etc/profile.d/

Contains system-wide configuration files for specific programs

~/.profile

Insert user specific configuration for login shells here

Note that the login shell also sources the configuration files listed under Table 1.2, “Bash Configuration Files for Non-Login Shells”.

Table 1.2: Bash Configuration Files for Non-Login Shells

/etc/bash.bashrc

Do not modify this file, otherwise your modifications can be destroyed during your next update!

/etc/bash.bashrc.local

Use this file to insert your system-wide modifications for Bash only

~/.bashrc

Insert user specific configuration here

Additionally, Bash uses some more files:

Table 1.3: Special Files for Bash

File

Description

~/.bash_history

Contains a list of all commands you have been typing

~/.bash_logout

Executed when logging out

~/.alias

User defined aliases of frequently used commands. See man 1 alias for more details about how to define aliases.

1.1.2 The Directory Structure

  • Filename: fs_structure_i.xml
  • ID: sec.adm.dirstructure

The following table provides a short overview of the most important higher-level directories that you find on a Linux system. Find more detailed information about the directories and important subdirectories in the following list.

Table 1.4: Overview of a Standard Directory Tree

Directory

Contents

/

Root directory—the starting point of the directory tree.

/bin

Essential binary files, such as commands that are needed by both the system administrator and normal users. Usually also contains the shells, such as Bash.

/boot

Static files of the boot loader.

/dev

Files needed to access host-specific devices.

/etc

Host-specific system configuration files.

/home

Holds the home directories of all users who have accounts on the system. However, root's home directory is not located in /home but in /root.

/lib

Essential shared libraries and kernel modules.

/media

Mount points for removable media.

/mnt

Mount point for temporarily mounting a file system.

/opt

Add-on application software packages.

/root

Home directory for the superuser root.

/sbin

Essential system binaries.

/srv

Data for services provided by the system.

/tmp

Temporary files.

/usr

Secondary hierarchy with read-only data.

/var

Variable data such as log files.

/windows

Only available if you have both Microsoft Windows* and Linux installed on your system. Contains the Windows data.

The following list provides more detailed information and gives some examples of which files and subdirectories can be found in the directories:

/bin

Contains the basic shell commands that may be used both by root and by other users. These commands include ls, mkdir, cp, mv, rm and rmdir. /bin also contains Bash, the default shell in SUSE Linux Enterprise Server.

/boot

Contains data required for booting, such as the boot loader, the kernel, and other data that is used before the kernel begins executing user-mode programs.

/dev

Holds device files that represent hardware components.

/etc

Contains local configuration files that control the operation of programs like the X Window System. The /etc/init.d subdirectory contains LSB init scripts that can be executed during the boot process.

/home/USERNAME

Holds the private data of every user who has an account on the system. The files located here can only be modified by their owner or by the system administrator. By default, your e-mail directory and personal desktop configuration are located here in the form of hidden files and directories, such as .gconf/ and .config.

Note
Note: Home Directory in a Network Environment

If you are working in a network environment, your home directory may be mapped to a directory in the file system other than /home.

/lib

Contains the essential shared libraries needed to boot the system and to run the commands in the root file system. The Windows equivalent for shared libraries are DLL files.

/media

Contains mount points for removable media, such as CD-ROMs, flash disks, and digital cameras (if they use USB). /media generally holds any type of drive except the hard disk of your system. When your removable medium has been inserted or connected to the system and has been mounted, you can access it from here.

/mnt

This directory provides a mount point for a temporarily mounted file system. root may mount file systems here.

/opt

Reserved for the installation of third-party software. Optional software and larger add-on program packages can be found here.

/root

Home directory for the root user. The personal data of root is located here.

/run

A tmpfs directory used by systemd and various components. /var/run is a symbolic link to /run.

/sbin

As the s indicates, this directory holds utilities for the superuser. /sbin contains the binaries essential for booting, restoring and recovering the system in addition to the binaries in /bin.

/srv

Holds data for services provided by the system, such as FTP and HTTP.

/tmp

This directory is used by programs that require temporary storage of files.

Important
Important: Cleaning up /tmp at Boot Time

Data stored in /tmp is not guaranteed to survive a system reboot. It depends, for example, on settings made in /etc/tmpfiles.d/tmp.conf.

/usr

/usr has nothing to do with users, but is the acronym for Unix system resources. The data in /usr is static, read-only data that can be shared among various hosts compliant with the Filesystem Hierarchy Standard (FHS). This directory contains all application programs including the graphical desktops such as GNOME and establishes a secondary hierarchy in the file system. /usr holds several subdirectories, such as /usr/bin, /usr/sbin, /usr/local, and /usr/share/doc.

/usr/bin

Contains generally accessible programs.

/usr/sbin

Contains programs reserved for the system administrator, such as repair functions.

/usr/local

In this directory the system administrator can install local, distribution-independent extensions.

/usr/share/doc

Holds various documentation files and the release notes for your system. In the manual subdirectory find an online version of this manual. If more than one language is installed, this directory may contain versions of the manuals for different languages.

Under packages find the documentation included in the software packages installed on your system. For every package, a subdirectory /usr/share/doc/packages/PACKAGENAME is created that often holds README files for the package and sometimes examples, configuration files or additional scripts.

If HOWTOs are installed on your system /usr/share/doc also holds the howto subdirectory in which to find additional documentation on many tasks related to the setup and operation of Linux software.

/var

Whereas /usr holds static, read-only data, /var is for data which is written during system operation and thus is variable data, such as log files or spooling data. For an overview of the most important log files you can find under /var/log/, refer to Table 40.1, “Log Files”.

1.2 Writing Shell Scripts

Shell scripts provide a convenient way to perform a wide range of tasks: collecting data, searching for a word or phrase in a text and other useful things. The following example shows a small shell script that prints a text:

Example 1.1: A Shell Script Printing a Text
#!/bin/sh 1
# Output the following line: 2
echo "Hello World" 3

1

The first line begins with the Shebang characters (#!) which is an indicator that this file is a script. The script is executed with the specified interpreter after the Shebang, in this case /bin/sh.

2

The second line is a comment beginning with the hash sign. It is recommended to comment difficult lines to remember what they do.

3

The third line uses the built-in command echo to print the corresponding text.

Before you can run this script you need some prerequisites:

  1. Every script should contain a Shebang line (as in the example above.) If the line is missing, you need to call the interpreter manually.

  2. You can save the script wherever you want. However, it is a good idea to save it in a directory where the shell can find it. The search path in a shell is determined by the environment variable PATH. Usually a normal user does not have write access to /usr/bin. Therefore it is recommended to save your scripts in the users' directory ~/bin/. The above example gets the name hello.sh.

  3. The script needs executable permissions. Set the permissions with the following command:

    chmod +x ~/bin/hello.sh

If you have fulfilled all of the above prerequisites, you can execute the script in the following ways:

  1. As Absolute Path.  The script can be executed with an absolute path. In our case, it is ~/bin/hello.sh.

  2. Everywhere.  If the PATH environment variable contains the directory where the script is located, you can execute the script with hello.sh.

1.3 Redirecting Command Events

Each command can use three channels, either for input or output:

  • Standard Output.  This is the default output channel. Whenever a command prints something, it uses the standard output channel.

  • Standard Input.  If a command needs input from users or other commands, it uses this channel.

  • Standard Error.  Commands use this channel for error reporting.

To redirect these channels, there are the following possibilities:

Command > File

Saves the output of the command into a file, an existing file will be deleted. For example, the ls command writes its output into the file listing.txt:

ls > listing.txt
Command >> File

Appends the output of the command to a file. For example, the ls command appends its output to the file listing.txt:

ls >> listing.txt
Command < File

Reads the file as input for the given command. For example, the read command reads in the content of the file into the variable:

read a < foo
Command1 | Command2

Redirects the output of the left command as input for the right command. For example, the cat command outputs the content of the /proc/cpuinfo file. This output is used by grep to filter only those lines which contain cpu:

cat /proc/cpuinfo | grep cpu

Every channel has a file descriptor: 0 (zero) for standard input, 1 for standard output and 2 for standard error. It is allowed to insert this file descriptor before a < or > character. For example, the following line searches for a file starting with foo, but suppresses its errors by redirecting it to /dev/null:

find / -name "foo*" 2>/dev/null

1.4 Using Aliases

An alias is a shortcut definition of one or more commands. The syntax for an alias is:

alias NAME=DEFINITION

For example, the following line defines an alias lt that outputs a long listing (option -l), sorts it by modification time (-t), and prints it in reverse sorted order (-r):

alias lt='ls -ltr'

To view all alias definitions, use alias. Remove your alias with unalias and the corresponding alias name.

1.5 Using Variables in Bash

A shell variable can be global or local. Global variables, or environment variables, can be accessed in all shells. In contrast, local variables are visible in the current shell only.

To view all environment variables, use the printenv command. If you need to know the value of a variable, insert the name of your variable as an argument:

printenv PATH

A variable, be it global or local, can also be viewed with echo:

echo $PATH

To set a local variable, use a variable name followed by the equal sign, followed by the value:

PROJECT="SLED"

Do not insert spaces around the equal sign, otherwise you get an error. To set an environment variable, use export:

export NAME="tux"

To remove a variable, use unset:

unset NAME

The following table contains some common environment variables which can be used in you shell scripts:

Table 1.5: Useful Environment Variables

HOME

the home directory of the current user

HOST

the current host name

LANG

when a tool is localized, it uses the language from this environment variable. English can also be set to C

PATH

the search path of the shell, a list of directories separated by colon

PS1

specifies the normal prompt printed before each command

PS2

specifies the secondary prompt printed when you execute a multi-line command

PWD

current working directory

USER

the current user

1.5.1 Using Argument Variables

For example, if you have the script foo.sh you can execute it like this:

foo.sh "Tux Penguin" 2000

To access all the arguments which are passed to your script, you need positional parameters. These are $1 for the first argument, $2 for the second, and so on. You can have up to nine parameters. To get the script name, use $0.

The following script foo.sh prints all arguments from 1 to 4:

#!/bin/sh
echo \"$1\" \"$2\" \"$3\" \"$4\"

If you execute this script with the above arguments, you get:

"Tux Penguin" "2000" "" ""

1.5.2 Using Variable Substitution

Variable substitutions apply a pattern to the content of a variable either from the left or right side. The following list contains the possible syntax forms:

${VAR#pattern}

removes the shortest possible match from the left:

file=/home/tux/book/book.tar.bz2
echo ${file#*/}
home/tux/book/book.tar.bz2
${VAR##pattern}

removes the longest possible match from the left:

file=/home/tux/book/book.tar.bz2
echo ${file##*/}
book.tar.bz2
${VAR%pattern}

removes the shortest possible match from the right:

file=/home/tux/book/book.tar.bz2
echo ${file%.*}
/home/tux/book/book.tar
${VAR%%pattern}

removes the longest possible match from the right:

file=/home/tux/book/book.tar.bz2
echo ${file%%.*}
/home/tux/book/book
${VAR/pattern_1/pattern_2}

substitutes the content of VAR from the PATTERN_1 with PATTERN_2:

file=/home/tux/book/book.tar.bz2
echo ${file/tux/wilber}
/home/wilber/book/book.tar.bz2

1.6 Grouping and Combining Commands

Shells allow you to concatenate and group commands for conditional execution. Each command returns an exit code which determines the success or failure of its operation. If it is 0 (zero) the command was successful, everything else marks an error which is specific to the command.

The following list shows, how commands can be grouped:

Command1 ; Command2

executes the commands in sequential order. The exit code is not checked. The following line displays the content of the file with cat and then prints its file properties with ls regardless of their exit codes:

cat filelist.txt ; ls -l filelist.txt
Command1 && Command2

runs the right command, if the left command was successful (logical AND). The following line displays the content of the file and prints its file properties only, when the previous command was successful (compare it with the previous entry in this list):

cat filelist.txt && ls -l filelist.txt
Command1 || Command2

runs the right command, when the left command has failed (logical OR). The following line creates only a directory in /home/wilber/bar when the creation of the directory in /home/tux/foo has failed:

mkdir /home/tux/foo || mkdir /home/wilber/bar
funcname(){ ... }

creates a shell function. You can use the positional parameters to access its arguments. The following line defines the function hello to print a short message:

hello() { echo "Hello $1"; }

You can call this function like this:

hello Tux

which prints:

Hello Tux

1.7 Working with Common Flow Constructs

To control the flow of your script, a shell has while, if, for and case constructs.

1.7.1 The if Control Command

The if command is used to check expressions. For example, the following code tests whether the current user is Tux:

if test $USER = "tux"; then
  echo "Hello Tux."
else
  echo "You are not Tux."
fi

The test expression can be as complex or simple as possible. The following expression checks if the file foo.txt exists:

if test -e /tmp/foo.txt ; then
  echo "Found foo.txt"
fi

The test expression can also be abbreviated in angled brackets:

if [ -e /tmp/foo.txt ] ; then
  echo "Found foo.txt"
fi

Find more useful expressions at http://www.cyberciti.biz/nixcraft/linux/docs/uniqlinuxfeatures/lsst/ch03sec02.html.

1.7.2 Creating Loops with the for Command

The for loop allows you to execute commands to a list of entries. For example, the following code prints some information about PNG files in the current directory:

for i in *.png; do
 ls -l $i
done

1.8 For More Information

Important information about Bash is provided in the man pages man bash. More about this topic can be found in the following list:

2 sudo

  • Filename: adm_sudo.xml
  • ID: cha.adm.sudo

Many commands and system utilities need to be run as root to modify files and/or perform tasks that only the super user is allowed to. For security reasons and to avoid accidentally running dangerous commands, it is generally advisable not to log in directly as root. Instead, it is recommended to work as a normal, unprivileged user and use the sudo command to run commands with elevated privileges.

On SUSE Linux Enterprise Server, sudo is configured by default to work similarly to su. However, sudo offers the possibility to allow users to run commands with privileges of any other user in a highly configurable manner. This can be used to assign roles with specific privileges to certain users and groups. It is for example possible to allow members of the group users to run a command with the privileges of wilber. Access to the command can be further restricted by, for example, forbidding to specify any command options. While su always requires the root password for authentication with PAM, sudo can be configured to authenticate with your own credentials. This increases security by not having to share the root password. For example, you can allow members of the group users to run a command frobnicate as wilber, with the restriction that no arguments are specified. This can be used to assign roles with specific abilities to certain users and groups.

2.1 Basic sudo Usage

sudo is simple to use, yet very powerful.

2.1.1 Running a Single Command

Logged in as normal user, you can run any command as root by adding sudo before it. It will prompt for the root password and, if authenticated successfully, run the command as root:

tux > id -un1
tux
tux > sudo id -un
root's password:2
root
tux > id -un
tux3
tux > sudo id -un
4
root

1

The id -un command prints the login name of the current user.

2

The password is not shown during input, neither as clear text nor as bullets.

3

Only commands started with sudo are run with elevated privileges. If you run the same command without the sudo prefix, it is run with the privileges of the current user again.

4

For a limited amount of time, you do not need to enter the root password again.

Tip
Tip: I/O Redirection

I/O redirection does not work as you would probably expect:

tux >  sudo echo s > /proc/sysrq-trigger
bash: /proc/sysrq-trigger: Permission denied
tux >  sudo cat < /proc/1/maps
bash: /proc/1/maps: Permission denied

Only the echo/cat binary is run with elevated privileges, while the redirection is performed by the user's shell with user privileges. You can either start a shell like in Section 2.1.2, “Starting a Shell” or use the dd utility instead:

echo s | sudo dd of=/proc/sysrq-trigger
sudo dd if=/proc/1/maps | cat

2.1.2 Starting a Shell

Having to add sudo before every command can be cumbersome. While you could specify a shell as a command sudo bash, it is recommended to rather use one of the built-in mechanisms to start a shell:

sudo -s (<command>)

Starts a shell specified by the SHELL environment variable or the target user's default shell. If a command is given, it is passed to the shell (with the -c option), else the shell is run in interactive mode.

tux:~ > sudo -i
root's password:
root:/home/tux # exit
tux:~ > 
sudo -i (<command>)

Like -s, but starts the shell as login shell. This means that the shell's start-up files (.profile etc.) are processed and the current working directory is set to the target user's home directory.

tux:~ > sudo -i
root's password:
root:~ # exit
tux:~ > 

2.1.3 Environment Variables

By default, sudo does not propagate environment variables:

tux > ENVVAR=test env | grep ENVVAR
ENVVAR=test
tux > ENVVAR=test sudo env | grep ENVVAR
root's password:
1
tux > 

1

The empty output shows that the environment variable ENVVAR did not exist in the context of the command run with sudo.

This behavior can be changed by the env_reset option, see Table 2.1, “Useful Flags and Options”.

2.2 Configuring sudo

sudo is a very flexible tool with extensive configuration.

Note
Note: Locked yourself out of sudo

If you accidentally locked yourself out of sudo, use su - and the root password to get a root shell. To fix the error, run visudo.

2.2.1 Editing the Configuration Files

The main policy configuration file for sudo is /etc/sudoers. As it is possible to lock yourself out of the system due to errors in this file, it is strongly recommended to use visudo for editing. It will prevent simultaneous changes to the opened file and check for syntax errors before saving the modifications.

Despite its name, you can also use editors other than vi by setting the EDITOR environment variable, for example:

sudo EDITOR=/usr/bin/nano visudo

However, the /etc/sudoers file itself is supplied by the system packages and modifications may break on updates. Therefore, it is recommended to put custom configuration into files in the /etc/sudoers.d/ directory. Any file in there is automatically included. To create or edit a file in that subdirectory, run:

sudo visudo -f /etc/sudoers.d/NAME

Alternatively with a different editor (for example nano):

sudo EDITOR=/usr/bin/nano visudo -f /etc/sudoers.d/NAME
Note
Note: Ignored Files in /etc/sudoers.d

The #includedir command in /etc/sudoers, used for /etc/sudoers.d, ignores files that end in ~ (tilde) or contain a . (dot).

For more information on the visudo command, run man 8 visudo.

2.2.2 Basic sudoers Configuration Syntax

In the sudoers configuration files, there are two types of options: strings and flags. While strings can contain any value, flags can be turned either ON or OFF. The most important syntax constructs for sudoers configuration files are:

# Everything on a line after a # gets ignored 1
Defaults !insults # Disable the insults flag 2
Defaults env_keep += "DISPLAY HOME" # Add DISPLAY and HOME to env_keep
tux ALL = NOPASSWD: /usr/bin/frobnicate, PASSWD: /usr/bin/journalctl 3

1

There are two exceptions: #include and #includedir are normal commands. Followed by digits, it specifies a UID.

2

Remove the ! to set the specified flag to ON.

3

See Section 2.2.3, “Rules in sudoers”.

Table 2.1: Useful Flags and Options

Option name

Description

Example

targetpw

This flag controls whether the invoking user is required to enter the password of the target user (ON) (for example root) or the invoking user (OFF).

Defaults targetpw # Turn targetpw flag ON
rootpw

If set, sudo will prompt for the root password instead of the target user's or the invoker's. The default is OFF.

Defaults !rootpw # Turn rootpw flag OFF
env_reset

If set, sudo constructs a minimal environment with only TERM, PATH, HOME, MAIL, SHELL, LOGNAME, USER, USERNAME, and SUDO_* set. Additionally, variables listed in env_keep get imported from the calling environment. The default is ON.

Defaults env_reset # Turn env_reset flag ON
env_keep

List of environment variables to keep when the env_reset flag is ON.

# Set env_keep to contain EDITOR and PROMPT
Defaults env_keep = "EDITOR PROMPT"
Defaults env_keep += "JRE_HOME" # Add JRE_HOME
Defaults env_keep -= "JRE_HOME" # Remove JRE_HOME
env_delete

List of environment variables to remove when the env_reset flag is OFF.

# Set env_delete to contain EDITOR and PROMPT
Defaults env_delete = "EDITOR PROMPT"
Defaults env_delete += "JRE_HOME" # Add JRE_HOME
Defaults env_delete -= "JRE_HOME" # Remove JRE_HOME

The Defaults token can also be used to create aliases for a collection of users, hosts, and commands. Furthermore, it is possible to apply an option only to a specific set of users.

For detailed information about the /etc/sudoers configuration file, consult man 5 sudoers.

2.2.3 Rules in sudoers

Rules in the sudoers configuration can be very complex, so this section will only cover the basics. Each rule follows the basic scheme ([] marks optional parts):

#Who      Where         As whom      Tag                What
User_List Host_List = [(User_List)] [NOPASSWD:|PASSWD:] Cmnd_List
Syntax for sudoers Rules
User_List

One or more (separated by ,) identifiers: Either a user name, a group in the format %GROUPNAME or a user ID in the format #UID. Negation can be performed with a ! prefix.

Host_List

One or more (separated by ,) identifiers: Either a (fully qualified) host name or an IP address. Negation can be performed with a ! prefix. ALL is the usual choice for Host_List.

NOPASSWD:|PASSWD:

The user will not be prompted for a password when running commands matching CMDSPEC after NOPASSWD:.

PASSWD is the default, it only needs to be specified when both are on the same line:

tux ALL = PASSWD: /usr/bin/foo, NOPASSWD: /usr/bin/bar
Cmnd_List

One or more (separated by ,) specifiers: A path to an executable, followed by allowed arguments or nothing.

/usr/bin/foo     # Anything allowed
/usr/bin/foo bar # Only "/usr/bin/foo bar" allowed
/usr/bin/foo ""  # No arguments allowed

ALL can be used as User_List, Host_List, and Cmnd_List.

A rule that allows tux to run all commands as root without entering a password:

tux ALL = NOPASSWD: ALL

A rule that allows tux to run systemctl restart apache2:

tux ALL = /usr/bin/systemctl restart apache2

A rule that allows tux to run wall as admin with no arguments:

tux ALL = (admin) /usr/bin/wall ""
Warning
Warning: Dangerous constructs

Constructs of the kind

ALL ALL = ALL

must not be used without Defaults targetpw, otherwise anyone can run commands as root.

2.3 Common Use Cases

Although the default configuration is often sufficient for simple setups and desktop environments, custom configurations can be very useful.

2.3.1 Using sudo without root Password

In cases with special restrictions (user X can only run command Y as root) it is not possible. In other cases, it is still favorable to have some kind of separation. By convention, members of the group wheel can run all commands with sudo as root.

  1. Add yourself to the wheel group

    If your user account is not already member of the wheel group, add it by running sudo usermod -a -G wheel USERNAME and logging out and in again. Verify that the change was successful by running groups USERNAME.

  2. Make authentication with the invoking user's password the default.

    Create the file /etc/sudoers.d/userpw with visudo (see Section 2.2.1, “Editing the Configuration Files”) and add:

    Defaults !targetpw
  3. Select a new default rule.

    Depending on whether you want users to re-enter their passwords, uncomment the specific line in /etc/sudoers and comment out the default rule.

    ## Uncomment to allow members of group wheel to execute any command
    # %wheel ALL=(ALL) ALL
    
    ## Same thing without a password
    # %wheel ALL=(ALL) NOPASSWD: ALL
  4. Make the default rule more restrictive

    Comment out or remove the allow-everything rule in /etc/sudoers:

    ALL     ALL=(ALL) ALL   # WARNING! Only use this together with 'Defaults targetpw'!
    Warning
    Warning: Dangerous rule in sudoers

    Do not forget this step, otherwise any user can execute any command as root!

  5. Test the configuration

    Try to run sudo as member and non-member of wheel.

    tux:~ > groups
    users wheel
    tux:~ > sudo id -un
    tux's password:
    root
    wilber:~ > groups
    users
    wilber:~ > sudo id -un
    wilber is not in the sudoers file.  This incident will be reported.

2.3.2 Using sudo with X.Org Applications

When starting graphical applications with sudo, you will encounter the following error:

tux > sudo xterm
xterm: Xt error: Can't open display: %s
xterm: DISPLAY is not set

YaST will pick the ncurses interface instead of the graphical one.

To use X.Org in applications started with sudo, the environment variables DISPLAY and XAUTHORITY need to be propagated. To configure this, create the file /etc/sudoers.d/xorg, (see Section 2.2.1, “Editing the Configuration Files”) and add the following line:

Defaults env_keep += "DISPLAY XAUTHORITY"

If not set already, set the XAUTHORITY variable as follows:

export XAUTHORITY=~/.Xauthority

Now X.Org applications can be run as usual:

sudo yast2

2.4 More Information

A quick overview about the available command line switches can be retrieved by sudo --help. An explanation and other important information can be found in the man page: man 8 sudo, while the configuration is documented in man 5 sudoers.

3 YaST Online Update

  • Filename: yast2_you.xml
  • ID: cha.onlineupdate.you

SUSE offers a continuous stream of software security updates for your product. By default, the update applet is used to keep your system up-to-date. Refer to Section 13.5, “Keeping the System Up-to-date” for further information on the update applet. This chapter covers the alternative tool for updating software packages: YaST Online Update.

The current patches for SUSE® Linux Enterprise Server are available from an update software repository. If you have registered your product during the installation, an update repository is already configured. If you have not registered SUSE Linux Enterprise Server, you can do so by starting the Product Registration in YaST. Alternatively, you can manually add an update repository from a source you trust. To add or remove repositories, start the Repository Manager with Software › Software Repositories in YaST. Learn more about the Repository Manager in Section 13.4, “Managing Software Repositories and Services”.

Note
Note: Error on Accessing the Update Catalog

If you are not able to access the update catalog, this might be because of an expired subscription. Normally, SUSE Linux Enterprise Server comes with a one-year or three-year subscription, during which you have access to the update catalog. This access will be denied after the subscription ends.

If an access to the update catalog is denied, you will see a warning message prompting you to visit the SUSE Customer Center and check your subscription. The SUSE Customer Center is available at https://scc.suse.com//.

SUSE provides updates with different relevance levels:

Security Updates

Fix severe security hazards and should always be installed.

Recommended Updates

Fix issues that could compromise your computer.

Optional Updates

Fix non-security relevant issues or provide enhancements.

3.1 The Online Update Dialog

To open the YaST Online Update dialog, start YaST and select Software  › Online Update. Alternatively, start it from the command line with yast2 online_update.

The Online Update window consists of four sections.

YaST Online Update
Figure 3.1: YaST Online Update

The Summary section on the left lists the available patches for SUSE Linux Enterprise Server. The patches are sorted by security relevance: security, recommended, and optional. You can change the view of the Summary section by selecting one of the following options from Show Patch Category:

Needed Patches (default view)

Non-installed patches that apply to packages installed on your system.

Unneeded Patches

Patches that either apply to packages not installed on your system, or patches that have requirements which have already have been fulfilled (because the relevant packages have already been updated from another source).

All Patches

All patches available for SUSE Linux Enterprise Server.

Each list entry in the Summary section consists of a symbol and the patch name. For an overview of the possible symbols and their meaning, press ShiftF1. Actions required by Security and Recommended patches are automatically preset. These actions are Autoinstall, Autoupdate and Autodelete.

If you install an up-to-date package from a repository other than the update repository, the requirements of a patch for this package may be fulfilled with this installation. In this case a check mark is displayed in front of the patch summary. The patch will be visible in the list until you mark it for installation. This will in fact not install the patch (because the package already is up-to-date), but mark the patch as having been installed.

Select an entry in the Summary section to view a short Patch Description at the bottom left corner of the dialog. The upper right section lists the packages included in the selected patch (a patch can consist of several packages). Click an entry in the upper right section to view details about the respective package that is included in the patch.

3.2 Installing Patches

The YaST Online Update dialog allows you to either install all available patches at once or manually select the desired patches. You may also revert patches that have been applied to the system.

By default, all new patches (except optional ones) that are currently available for your system are already marked for installation. They will be applied automatically once you click Accept or Apply. If one or multiple patches require a system reboot, you will be notified about this before the patch installation starts. You can then either decide to continue with the installation of the selected patches, skip the installation of all patches that need rebooting and install the rest, or go back to the manual patch selection.

Procedure 3.1: Applying Patches with YaST Online Update
  1. Start YaST and select Software › Online Update.

  2. To automatically apply all new patches (except optional ones) that are currently available for your system, press Apply or Accept.

  3. First modify the selection of patches that you want to apply:

    1. Use the respective filters and views that the interface provides. For details, refer to Section 3.1, “The Online Update Dialog”.

    2. Select or deselect patches according to your needs and wishes by right-clicking the patch and choosing the respective action from the context menu.

      Important
      Important: Always Apply Security Updates

      Do not deselect any security-related patches without a very good reason. These patches fix severe security hazards and prevent your system from being exploited.

    3. Most patches include updates for several packages. If you want to change actions for single packages, right-click a package in the package view and choose an action.

    4. To confirm your selection and apply the selected patches, proceed with Apply or Accept.

  4. After the installation is complete, click Finish to leave the YaST Online Update. Your system is now up-to-date.

3.3 Automatic Online Update

YaST also offers the possibility to set up an automatic update with daily, weekly or monthly schedule. To use the respective module, you need to install the yast2-online-update-configuration package first.

By default, updates are downloaded as delta RPMs. Since rebuilding RPM packages from delta RPMs is a memory- and processor-intensive task, certain setups or hardware configurations might require you to disable the use of delta RPMs for the sake of performance.

Some patches, such as kernel updates or packages requiring license agreements, require user interaction, which would cause the automatic update procedure to stop. You can configure to skip patches that require user interaction.

Procedure 3.2: Configuring the Automatic Online Update
  1. After installation, start YaST and select Software › Online Update Configuration.

    Alternatively, start the module with yast2 online_update_configuration from the command line.

  2. Activate Automatic Online Update.

  3. Choose the update interval: Daily, Weekly, or Monthly.

  4. To automatically accept any license agreements, activate Agree with Licenses.

  5. Select if you want to Skip Interactive Patches in case you want the update procedure to proceed fully automatically.

    Important
    Important: Skipping Patches

    If you select to skip any packages that require interaction, run a manual Online Update occasionally to install those patches, too. Otherwise you might miss important patches.

  6. To automatically install all packages recommended by updated packages, activate Include Recommended Packages.

  7. To disable the use of delta RPMs (for performance reasons), deactivate Use Delta RPMs.

  8. To filter the patches by category (such as security or recommended), activate Filter by Category and add the appropriate patch categories from the list. Only patches of the selected categories will be installed. Others will be skipped.

  9. Confirm your configuration with OK.

The automatic online update does not automatically restart the system afterward. If there are package updates that require a system reboot, you need to do this manually.

4 YaST

  • Filename: yast2_gui.xml
  • ID: cha.yast.gui

YaST is the installation and configuration tool for SUSE Linux Enterprise Server. It has a graphical interface and the capability to customize your system quickly during and after the installation. It can be used to set up hardware, configure the network, system services, and tune your security settings.

4.1 Advanced Key Combinations

YaST has a set of advanced key combinations.

Print Screen

Take and save a screenshot. May not be available when YaST is running under some desktop environments.

ShiftF4

Enable/disable the color palette optimized for vision impaired users.

ShiftF7

Enable/disable logging of debug messages.

ShiftF8

Open a file dialog to save log files to a non-standard location.

CtrlShiftAltD

Send a DebugEvent. YaST modules can react to this by executing special debugging actions. The result depends on the specific YaST module.

CtrlShiftAltM

Start/stop macro recorder.

CtrlShiftAltP

Replay macro.

CtrlShiftAltS

Show style sheet editor.

CtrlShiftAltT

Dump widget tree to the log file.

CtrlShiftAltX

Open a terminal window (xterm). Useful for installation process via VNC.

CtrlShiftAltY

Show widget tree browser.

5 YaST in Text Mode

  • Filename: yast2_ncurses.xml
  • ID: cha.yast.text

This section is intended for system administrators and experts who do not run an X server on their systems and depend on the text-based installation tool. It provides basic information about starting and operating YaST in text mode.

YaST in text mode uses the ncurses library to provide an easy pseudo-graphical user interface. The ncurses library is installed by default. The minimum supported size of the terminal emulator in which to run YaST is 80x25 characters.

Main Window of YaST in Text Mode
Figure 5.1: Main Window of YaST in Text Mode

When you start YaST in text mode, the YaST control center appears (see Figure 5.1). The main window consists of three areas. The left frame features the categories to which the various modules belong. This frame is active when YaST is started and therefore it is marked by a bold white border. The active category is selected. The right frame provides an overview of the modules available in the active category. The bottom frame contains the buttons for Help and Quit.

When you start the YaST control center, the category Software is selected automatically. Use and to change the category. To select a module from the category, activate the right frame with and then use and to select the module. Keep the arrow keys pressed to scroll through the list of available modules. The selected module is selected. Press Enter to start the active module.

Various buttons or selection fields in the module contain a highlighted letter (yellow by default). Use Althighlighted_letter to select a button directly instead of navigating there with →|. Exit the YaST control center by pressing AltQ or by selecting Quit and pressing Enter.

Tip
Tip: Refreshing YaST Dialogs

If a YaST dialog gets corrupted or distorted (for example, while resizing the window), press CtrlL to refresh and restore its contents.

5.1 Navigation in Modules

The following description of the control elements in the YaST modules assumes that all function keys and Alt key combinations work and are not assigned to different global functions. Read Section 5.3, “Restriction of Key Combinations” for information about possible exceptions.

Navigation among Buttons and Selection Lists

Use →| to navigate among the buttons and frames containing selection lists. To navigate in reverse order, use Alt→| or Shift→| combinations.

Navigation in Selection Lists

Use the arrow keys ( and ) to navigate among the individual elements in an active frame containing a selection list. If individual entries within a frame exceed its width, use Shift or Shift to scroll horizontally to the right and left. Alternatively, use CtrlE or CtrlA. This combination can also be used if using or results in changing the active frame or the current selection list, as in the control center.

Buttons, Radio Buttons, and Check Boxes

To select buttons with empty square brackets (check boxes) or empty parentheses (radio buttons), press Space or Enter. Alternatively, radio buttons and check boxes can be selected directly with Althighlighted_letter. In this case, you do not need to confirm with Enter. If you navigate to an item with →|, press Enter to execute the selected action or activate the respective menu item.

Function Keys

The function keys (F1 ... F12) enable quick access to the various buttons. Available function key combinations (FX) are shown in the bottom line of the YaST screen. Which function keys are actually mapped to which buttons depend on the active YaST module, because the different modules offer different buttons (Details, Info, Add, Delete, etc.). Use F10 for Accept, OK, Next, and Finish. Press F1 to access the YaST help.

Using Navigation Tree in ncurses Mode

Some YaST modules use a navigation tree in the left part of the window to select configuration dialogs. Use the arrow keys ( and ) to navigate in the tree. Use Space to open or close tree items. In ncurses mode, Enter must be pressed after a selection in the navigation tree to show the selected dialog. This is an intentional behavior to save time consuming redraws when browsing through the navigation tree.

Selecting Software in the Software Installation Module

Use the filters on the left side to limit the amount of displayed packages. Installed packages are marked with the letter i. To change the status of a package, press Space or Enter. Alternatively, use the Actions menu to select the needed status change (install, delete, update, taboo or lock).

The Software Installation Module
Figure 5.2: The Software Installation Module

5.2 Advanced Key Combinations

YaST in text mode has a set of advanced key combinations.

ShiftF1

Show a list of advanced hotkeys.

ShiftF4

Change color schema.

Ctrl\

Quit the application.

CtrlL

Refresh screen.

CtrlD F1

Show a list of advanced hotkeys.

CtrlD ShiftD

Dump dialog to the log file as a screenshot.

CtrlD ShiftY

Open YDialogSpy to see the widget hierarchy.

5.3 Restriction of Key Combinations

If your window manager uses global Alt combinations, the Alt combinations in YaST might not work. Keys like Alt or Shift can also be occupied by the settings of the terminal.

Replacing Alt with Esc

Alt shortcuts can be executed with Esc instead of Alt. For example, EscH replaces AltH. (First press Esc, then press H.)

Backward and Forward Navigation with CtrlF and CtrlB

If the Alt and Shift combinations are occupied by the window manager or the terminal, use the combinations CtrlF (forward) and CtrlB (backward) instead.

Restriction of Function Keys

The function keys (F1 ... F12) are also used for functions. Certain function keys might be occupied by the terminal and may not be available for YaST. However, the Alt key combinations and function keys should always be fully available on a pure text console.

5.4 YaST Command Line Options

Besides the text mode interface, YaST provides a pure command line interface. To get a list of YaST command line options, enter:

yast -h

5.4.1 Starting the Individual Modules

To save time, the individual YaST modules can be started directly. To start a module, enter:

yast <module_name>

View a list of all module names available on your system with yast -l or yast --list. Start the network module, for example, with yast lan.

5.4.2 Installing Packages from the Command Line

If you know a package name and the package is provided by any of your active installation repositories, you can use the command line option -i to install the package:

yast -i <package_name>

or

yast --install <package_name>

PACKAGE_NAME can be a single short package name (for example gvim) installed with dependency checking, or the full path to an RPM package which is installed without dependency checking.

If you need a command line based software management utility with functionality beyond what YaST provides, consider using Zypper. This utility uses the same software management library that is also the foundation for the YaST package manager. The basic usage of Zypper is covered in Section 6.1, “Using Zypper”.

5.4.3 Command Line Parameters of the YaST Modules

To use YaST functionality in scripts, YaST provides command line support for individual modules. Not all modules have command line support. To display the available options of a module, enter:

yast <module_name> help

If a module does not provide command line support, the module is started in text mode and the following message appears:

This YaST module does not support the command line interface.

6 Managing Software with Command Line Tools

  • Filename: sw_managing_commandline.xml
  • ID: cha.sw_cl
Abstract

This chapter describes Zypper and RPM, two command line tools for managing software. For a definition of the terminology used in this context (for example, repository, patch, or update) refer to Section 13.1, “Definition of Terms”.

6.1 Using Zypper

  • Filename: zypper.xml
  • ID: sec.zypper

Zypper is a command line package manager for installing, updating and removing packages a well as for managing repositories. It is especially useful for accomplishing remote software management tasks or managing software from shell scripts.

6.1.1 General Usage

The general syntax of Zypper is:

zypper [--global-options] COMMAND  [--command-options] [arguments]

The components enclosed in brackets are not required. See zypper help for a list of general options and all commands. To get help for a specific command, type zypper help COMMAND.

Zypper Commands

The simplest way to execute Zypper is to type its name, followed by a command. For example, to apply all needed patches to the system, use:

tux > sudo zypper patch
Global Options

Additionally, you can choose from one or more global options by typing them immediately before the command:

tux > sudo zypper --non-interactive patch

In the above example, the option --non-interactive means that the command is run without asking anything (automatically applying the default answers).

Command-Specific Options

To use options that are specific to a particular command, type them immediately after the command:

tux > sudo zypper patch --auto-agree-with-licenses

In the above example, --auto-agree-with-licenses is used to apply all needed patches to a system without you being asked to confirm any licenses. Instead, license will be accepted automatically.

Arguments

Some commands require one or more arguments. For example, when using the command install, you need to specify which package or which packages you want to install:

tux > sudo zypper install mplayer

Some options also require a single argument. The following command will list all known patterns:

tux > zypper search -t pattern

You can combine all of the above. For example, the following command will install the aspell-de and aspell-fr packages from the factory repository while being verbose:

tux > sudo zypper -v install --from factory aspell-de aspell-fr

The --from option makes sure to keep all repositories enabled (for solving any dependencies) while requesting the package from the specified repository.

Most Zypper commands have a dry-run option that does a simulation of the given command. It can be used for test purposes.

tux > sudo zypper remove --dry-run MozillaFirefox

Zypper supports the global --userdata STRING option. You can specify a string with this option, which gets written to Zypper's log files and plug-ins (such as the Btrfs plug-in). It can be used to mark and identify transactions in log files.

tux > sudo zypper --userdata STRING patch

6.1.2 Installing and Removing Software with Zypper

To install or remove packages, use the following commands:

tux > sudo zypper install PACKAGE_NAME
sudo zypper remove PACKAGE_NAME
Warning
Warning: Do Not Remove Mandatory System Packages

Do not remove mandatory system packages like glibc , zypper , kernel . If they are removed, the system can become unstable or stop working altogether.

6.1.2.1 Selecting Which Packages to Install or Remove

There are various ways to address packages with the commands zypper install and zypper remove.

By Exact Package Name
tux > sudo zypper install MozillaFirefox
By Exact Package Name and Version Number
tux > sudo zypper install MozillaFirefox-52.2
By Repository Alias and Package Name
tux > sudo zypper install mozilla:MozillaFirefox

Where mozilla is the alias of the repository from which to install.

By Package Name Using Wild Cards

You can select all packages that have names starting or ending with a certain string. Use wild cards with care, especially when removing packages. The following command will install all packages starting with Moz:

tux > sudo zypper install 'Moz*'
Tip
Tip: Removing all -debuginfo Packages

When debugging a problem, you sometimes need to temporarily install a lot of -debuginfo packages which give you more information about running processes. After your debugging session finishes and you need to clean the environment, run the following:

tux > sudo zypper remove '*-debuginfo'
By Capability

For example, if you want to install a Perl module without knowing the name of the package, capabilities come in handy:

tux > sudo zypper install firefox
By Capability, Hardware Architecture, or Version

Together with a capability, you can specify a hardware architecture and a version:

  • The name of the desired hardware architecture is appended to the capability after a full stop. For example, to specify the AMD64/Intel 64 architectures (which in Zypper is named x86_64), use:

    tux > sudo zypper install 'firefox.x86_64'
  • Versions must be appended to the end of the string and must be preceded by an operator: < (lesser than), <= (lesser than or equal), = (equal), >= (greater than or equal), > (greater than).

    tux > sudo zypper install 'firefox>=52.2'
  • You can also combine a hardware architecture and version requirement:

    tux > sudo zypper install 'firefox.x86_64>=52.2'
By Path to the RPM file

You can also specify a local or remote path to a package:

tux > sudo zypper install /tmp/install/MozillaFirefox.rpm
tux > sudo zypper install http://download.example.com/MozillaFirefox.rpm

6.1.2.2 Combining Installation and Removal of Packages

To install and remove packages simultaneously, use the +/- modifiers. To install emacs and simultaneously remove vim , use:

tux > sudo zypper install emacs -vim

To remove emacs and simultaneously install vim , use:

tux > sudo zypper remove emacs +vim

To prevent the package name starting with the - being interpreted as a command option, always use it as the second argument. If this is not possible, precede it with --:

tux > sudo zypper install -emacs +vim       # Wrong
tux > sudo zypper install vim -emacs        # Correct
tux > sudo zypper install -- -emacs +vim    # Correct
tux > sudo zypper remove emacs +vim         # Correct

6.1.2.3 Cleaning Up Dependencies of Removed Packages

If (together with a certain package), you automatically want to remove any packages that become unneeded after removing the specified package, use the --clean-deps option:

tux > sudo zypper rm PACKAGE_NAME --clean-deps

6.1.2.4 Using Zypper in Scripts

By default, Zypper asks for a confirmation before installing or removing a selected package, or when a problem occurs. You can override this behavior using the --non-interactive option. This option must be given before the actual command (install, remove, and patch), as can be seen in the following:

tux > sudo zypper --non-interactive install PACKAGE_NAME

This option allows the use of Zypper in scripts and cron jobs.

6.1.2.5 Installing or Downloading Source Packages

To install the corresponding source package of a package, use:

tux > zypper source-install PACKAGE_NAME

When executed as root, the default location to install source packages is /usr/src/packages/ and ~/rpmbuild when run as user. These values can be changed in your local rpm configuration.

This command will also install the build dependencies of the specified package. If you do not want this, add the switch -D:

tux > sudo zypper source-install -D PACKAGE_NAME

To install only the build dependencies use -d.

tux > sudo zypper source-install -d PACKAGE_NAME

Of course, this will only work if you have the repository with the source packages enabled in your repository list (it is added by default, but not enabled). See Section 6.1.5, “Managing Repositories with Zypper” for details on repository management.

A list of all source packages available in your repositories can be obtained with:

tux > zypper search -t srcpackage

You can also download source packages for all installed packages to a local directory. To download source packages, use:

tux > zypper source-download

The default download directory is /var/cache/zypper/source-download. You can change it using the --directory option. To only show missing or extraneous packages without downloading or deleting anything, use the --status option. To delete extraneous source packages, use the --delete option. To disable deleting, use the --no-delete option.

6.1.2.6 Installing Packages from Disabled Repositories

Normally you can only install or refresh packages from enabled repositories. The --plus-content TAG option helps you specify repositories to be refreshed, temporarily enabled during the current Zypper session, and disabled after it completes.

For example, to enable repositories that may provide additional -debuginfo or -debugsource packages, use --plus-content debug. You can specify this option multiple times.

To temporarily enable such 'debug' repositories to install a specific -debuginfo package, use the option as follows:

tux > sudo zypper --plus-content debug \
   install "debuginfo(build-id)=eb844a5c20c70a59fc693cd1061f851fb7d046f4"

The build-id string is reported by gdb for missing debuginfo packages.

6.1.2.7 Utilities

To verify whether all dependencies are still fulfilled and to repair missing dependencies, use:

tux > zypper verify

In addition to dependencies that must be fulfilled, some packages recommend other packages. These recommended packages are only installed if actually available and installable. In case recommended packages were made available after the recommending package has been installed (by adding additional packages or hardware), use the following command:

tux > sudo zypper install-new-recommends

This command is very useful after plugging in a Web cam or Wi-Fi device. It will install drivers for the device and related software, if available. Drivers and related software are only installable if certain hardware dependencies are fulfilled.

6.1.3 Updating Software with Zypper

There are three different ways to update software using Zypper: by installing patches, by installing a new version of a package or by updating the entire distribution. The latter is achieved with zypper dist-upgrade. Upgrading SUSE Linux Enterprise Server is discussed in Chapter 19, Upgrading SUSE Linux Enterprise .

6.1.3.1 Installing All Needed Patches

To install all officially released patches that apply to your system, run:

tux > sudo zypper patch

All patches available from repositories configured on your computer are checked for their relevance to your installation. If they are relevant (and not classified as optional or feature), they are installed immediately. Note that the official update repository is only available after registering your SUSE Linux Enterprise Server installation.

If a patch that is about to be installed includes changes that require a system reboot, you will be warned before.

The plain zypper patch command does not apply patches from third party repositories. To update also the third party repositories, use the with-update command option as follows:

tux > sudo zypper patch --with update

To install also optional patches, use:

tux > sudo zypper patch --with-optional

To install all patches relating to a specific Bugzilla issue, use:

tux > sudo zypper patch --bugzilla=NUMBER

To install all patches relating to a specific CVE database entry, use:

tux > sudo zypper patch --cve=NUMBER

For example, to install a security patch with the CVE number CVE-2010-2713, execute:

tux > sudo zypper patch --cve=CVE-2010-2713

To install only patches which affect Zypper and the package management itself, use:

tux > sudo zypper patch --updatestack-only

Bear in mind that other command options that would also update other repositories will be dropped if you use the updatestack-only command option.

6.1.3.2 Listing Patches

To find out whether patches are available, Zypper allows viewing the following information:

Number of Needed Patches

To list the number of needed patches (patches that apply to your system but are not yet installed), use patch-check:

tux > zypper patch-check
Loading repository data...
Reading installed packages...
5 patches needed (1 security patch)

This command can be combined with the --updatestack-only option to list only the patches which affect Zypper and the package management itself.

List of Needed Patches

To list all needed patches (patches that apply to your system but are not yet installed), use list-patches:

tux > zypper list-patches
Loading repository data...
Reading installed packages...

Repository     | Name        | Version | Category | Status  | Summary
---------------+-------------+---------+----------+---------+---------
SLES12-Updates | SUSE-2014-8 | 1       | security | needed  | openssl: Update for OpenSSL
List of All Patches

To list all patches available for SUSE Linux Enterprise Server, regardless of whether they are already installed or apply to your installation, use zypper patches.

It is also possible to list and install patches relevant to specific issues. To list specific patches, use the zypper list-patches command with the following options:

By Bugzilla Issues

To list all needed patches that relate to Bugzilla issues, use the option --bugzilla.

To list patches for a specific bug, you can also specify a bug number: --bugzilla=NUMBER. To search for patches relating to multiple Bugzilla issues, add commas between the bug numbers, for example:

tux > zypper list-patches --bugzilla=972197,956917
By CVE Number

To list all needed patches that relate to an entry in the CVE database (Common Vulnerabilities and Exposures), use the option --cve.

To list patches for a specific CVE database entry, you can also specify a CVE number: --cve=NUMBER. To search for patches relating to multiple CVE database entries, add commas between the CVE numbers, for example:

tux > zypper list-patches --bugzilla=CVE-2016-2315,CVE-2016-2324

To list all patches regardless of whether they are needed, use the option --all additionally. For example, to list all patches with a CVE number assigned, use:

tux > zypper list-patches --all --cve
Issue | No.           | Patch             | Category    | Severity  | Status
------+---------------+-------------------+-------------+-----------+----------
cve   | CVE-2015-0287 | SUSE-SLE-Module.. | recommended | moderate  | needed
cve   | CVE-2014-3566 | SUSE-SLE-SERVER.. | recommended | moderate  | not needed
[...]

6.1.3.3 Installing New Package Versions

If a repository contains only new packages, but does not provide patches, zypper patch does not show any effect. To update all installed packages with newer available versions (while maintaining system integrity), use:

tux > sudo zypper update

To update individual packages, specify the package with either the update or install command:

tux > sudo zypper update PACKAGE_NAME
sudo zypper install PACKAGE_NAME

A list of all new installable packages can be obtained with the command:

tux > zypper list-updates

Note that this command only lists packages that match the following criteria:

  • has the same vendor like the already installed package,

  • is provided by repositories with at least the same priority than the already installed package,

  • is installable (all dependencies are satisfied).

A list of all new available packages (regardless whether installable or not) can be obtained with:

tux > sudo zypper list-updates --all

To find out why a new package cannot be installed, use the zypper install or zypper update command as described above.

6.1.3.4 Identifying Orphaned Packages

Whenever you remove a repository from Zypper or upgrade your system, some packages can get in an orphaned state. These orphaned packages belong to no active repository anymore. The following command gives you a list of these:

tux > sudo zypper packages --orphaned

With this list, you can decide if a package is still needed or can be removed safely.

6.1.4 Identifying Processes and Services Using Deleted Files

When patching, updating or removing packages, there may be running processes on the system which continue to use files having been deleted by the update or removal. Use zypper ps to list processes using deleted files. In case the process belongs to a known service, the service name is listed, making it easy to restart the service. By default zypper ps shows a table:

tux > zypper ps
PID   | PPID | UID | User  | Command      | Service      | Files
------+------+-----+-------+--------------+--------------+-------------------
814   | 1    | 481 | avahi | avahi-daemon | avahi-daemon | /lib64/ld-2.19.s->
      |      |     |       |              |              | /lib64/libdl-2.1->
      |      |     |       |              |              | /lib64/libpthrea->
      |      |     |       |              |              | /lib64/libc-2.19->
[...]
PID: ID of the process
PPID: ID of the parent process
UID: ID of the user running the process
Login: Login name of the user running the process
Command: Command used to execute the process
Service: Service name (only if command is associated with a system service)
Files: The list of the deleted files

The output format of zypper ps can be controlled as follows:

zypper ps-s

Create a short table not showing the deleted files.

tux > zypper ps -s
PID   | PPID | UID  | User    | Command      | Service
------+------+------+---------+--------------+--------------
814   | 1    | 481  | avahi   | avahi-daemon | avahi-daemon
817   | 1    | 0    | root    | irqbalance   | irqbalance
1567  | 1    | 0    | root    | sshd         | sshd
1761  | 1    | 0    | root    | master       | postfix
1764  | 1761 | 51   | postfix | pickup       | postfix
1765  | 1761 | 51   | postfix | qmgr         | postfix
2031  | 2027 | 1000 | tux     | bash         |
zypper ps-ss

Show only processes associated with a system service.

PID   | PPID | UID  | User    | Command      | Service
------+------+------+---------+--------------+--------------
814   | 1    | 481  | avahi   | avahi-daemon | avahi-daemon
817   | 1    | 0    | root    | irqbalance   | irqbalance
1567  | 1    | 0    | root    | sshd         | sshd
1761  | 1    | 0    | root    | master       | postfix
1764  | 1761 | 51   | postfix | pickup       | postfix
1765  | 1761 | 51   | postfix | qmgr         | postfix
zypper ps-sss

Only show system services using deleted files.

avahi-daemon
irqbalance
postfix
sshd
zypper ps--print "systemctl status %s"

Show the commands to retrieve status information for services which might need a restart.

systemctl status avahi-daemon
systemctl status irqbalance
systemctl status postfix
systemctl status sshd

For more information about service handling refer to Chapter 13, The systemd Daemon.

6.1.5 Managing Repositories with Zypper

All installation or patch commands of Zypper rely on a list of known repositories. To list all repositories known to the system, use the command:

tux > zypper repos

The result will look similar to the following output:

Example 6.1: Zypper—List of Known Repositories
tux > zypper repos
# | Alias        | Name          | Enabled | Refresh
--+--------------+---------------+---------+--------
1 | SLEHA-12-GEO | SLEHA-12-GEO  | Yes     | No
2 | SLEHA-12     | SLEHA-12      | Yes     | No
3 | SLES12       | SLES12        | Yes     | No

When specifying repositories in various commands, an alias, URI or repository number from the zypper repos command output can be used. A repository alias is a short version of the repository name for use in repository handling commands. Note that the repository numbers can change after modifying the list of repositories. The alias will never change by itself.

By default, details such as the URI or the priority of the repository are not displayed. Use the following command to list all details:

tux > zypper repos -d

6.1.5.1 Adding Repositories

To add a repository, run

tux > sudo zypper addrepo URI ALIAS

URI can either be an Internet repository, a network resource, a directory or a CD or DVD (see http://en.opensuse.org/openSUSE:Libzypp_URIs for details). The ALIAS is a shorthand and unique identifier of the repository. You can freely choose it, with the only exception that it needs to be unique. Zypper will issue a warning if you specify an alias that is already in use.

6.1.5.2 Refreshing Repositories

zypper enables you to fetch changes in packages from configured repositories. To fetch the changes, run:

tux > sudo zypper refresh
Note
Note: Default Behavior of zypper

By default, some commands perform refresh automatically, so you do not need to run the command explicitly.

The refresh command enables you to view changes also in disabled repositories, by using the --plus-content option:

tux > sudo zypper --plus-content refresh

This option fetches changes in repositories, but keeps the disabled repositories in the same state—disabled.

6.1.5.3 Removing Repositories

To remove a repository from the list, use the command zypper removerepo together with the alias or number of the repository you want to delete. For example, to remove the repository SLEHA-12-GEO from Example 6.1, “Zypper—List of Known Repositories”, use one of the following commands:

tux > sudo zypper removerepo 1
tux > sudo zypper removerepo "SLEHA-12-GEO"

6.1.5.4 Modifying Repositories

Enable or disable repositories with zypper modifyrepo. You can also alter the repository's properties (such as refreshing behavior, name or priority) with this command. The following command will enable the repository named updates, turn on auto-refresh and set its priority to 20:

tux > sudo zypper modifyrepo -er -p 20 'updates'

Modifying repositories is not limited to a single repository—you can also operate on groups:

-a: all repositories
-l: local repositories
-t: remote repositories
-m TYPE: repositories of a certain type (where TYPE can be one of the following: http, https, ftp, cd, dvd, dir, file, cifs, smb, nfs, hd, iso)

To rename a repository alias, use the renamerepo command. The following example changes the alias from Mozilla Firefox to firefox:

tux > sudo zypper renamerepo 'Mozilla Firefox' firefox

6.1.6 Querying Repositories and Packages with Zypper

Zypper offers various methods to query repositories or packages. To get lists of all products, patterns, packages or patches available, use the following commands:

tux > zypper products
tux > zypper patterns
tux > zypper packages
tux > zypper patches

To query all repositories for certain packages, use search. To get information regarding particular packages, use the info command.

6.1.6.1 zypper search Usage

The zypper search command works on package names, or, optionally, on package summaries and descriptions. String wrapped in / are interpreted as regular expressions. By default, the search is not case-sensitive.

Simple search for a package name containing fire
tux > zypper search "fire"
Simple search for the exact package MozillaFirefox
tux > zypper search --match-exact "MozillaFirefox"
Also search in package descriptions and summaries
tux > zypper search -d fire
Only display packages not already installed
tux > zypper search -u fire
Display packages containing the string fir not followed be e
tux > zypper se "/fir[^e]/"

6.1.6.2 zypper what-provides Usage

To search for packages which provide a special capability, use the command what-provides. For example, if you want to know which package provides the Perl module SVN::Core, use the following command:

tux > zypper what-provides 'perl(SVN::Core)'

The what-provides PACKAGE_NAME is similar to rpm -q --whatprovides PACKAGE_NAME, but RPM is only able to query the RPM database (that is the database of all installed packages). Zypper, on the other hand, will tell you about providers of the capability from any repository, not only those that are installed.

6.1.6.3 zypper info Usage

To query single packages, use info with an exact package name as an argument. This displays detailed information about a package. In case the package name does not match any package name from repositories, the command outputs detailed information for non-package matches. If you request a specific type (by using the -t option) and the type does not exist, the command outputs other available matches but without detailed information.

If you specify a source package, the command displays binary packages built from the source package. If you specify a binary package, the command outputs the source packages used to build the binary package.

To also show what is required/recommended by the package, use the options --requires and --recommends:

tux > zypper info --requires MozillaFirefox

6.1.7 Configuring Zypper

Zypper now comes with a configuration file, allowing you to permanently change Zypper's behavior (either system-wide or user-specific). For system-wide changes, edit /etc/zypp/zypper.conf. For user-specific changes, edit ~/.zypper.conf. If ~/.zypper.conf does not yet exist, you can use /etc/zypp/zypper.conf as a template: copy it to ~/.zypper.conf and adjust it to your liking. Refer to the comments in the file for help about the available options.

6.1.8 Troubleshooting

If you have trouble accessing packages from configured repositories (for example, Zypper cannot find a certain package even though you know it exists in one the repositories), refreshing the repositories may help:

tux > sudo zypper refresh

If that does not help, try

tux > sudo zypper refresh -fdb

This forces a complete refresh and rebuild of the database, including a forced download of raw metadata.

6.1.9 Zypper Rollback Feature on Btrfs File System

If the Btrfs file system is used on the root partition and snapper is installed, Zypper automatically calls snapper when committing changes to the file system to create appropriate file system snapshots. These snapshots can be used to revert any changes made by Zypper. See Chapter 7, System Recovery and Snapshot Management with Snapper for more information.

6.1.10 For More Information

For more information on managing software from the command line, enter zypper help, zypper help  COMMAND or refer to the zypper(8) man page. For a complete and detailed command reference, cheat sheets with the most important commands, and information on how to use Zypper in scripts and applications, refer to http://en.opensuse.org/SDB:Zypper_usage. A list of software changes for the latest SUSE Linux Enterprise Server version can be found at http://en.opensuse.org/openSUSE:Zypper versions.

6.2 RPM—the Package Manager

  • Filename: rpm.xml
  • ID: sec.rpm

RPM (RPM Package Manager) is used for managing software packages. Its main commands are rpm and rpmbuild. The powerful RPM database can be queried by the users, system administrators and package builders for detailed information about the installed software.

Essentially, rpm has five modes: installing, uninstalling (or updating) software packages, rebuilding the RPM database, querying RPM bases or individual RPM archives, integrity checking of packages and signing packages. rpmbuild can be used to build installable packages from pristine sources.

Installable RPM archives are packed in a special binary format. These archives consist of the program files to install and certain meta information used during the installation by rpm to configure the software package or stored in the RPM database for documentation purposes. RPM archives normally have the extension .rpm.

Tip
Tip: Software Development Packages

For several packages, the components needed for software development (libraries, headers, include files, etc.) have been put into separate packages. These development packages are only needed if you want to compile software yourself (for example, the most recent GNOME packages). They can be identified by the name extension -devel, such as the packages alsa-devel and gimp-devel.

6.2.1 Verifying Package Authenticity

RPM packages have a GPG signature. To verify the signature of an RPM package, use the command rpm --checksig  PACKAGE-1.2.3.rpm to determine whether the package originates from SUSE or from another trustworthy facility. This is especially recommended for update packages from the Internet.

While fixing issues in the operating system, you might need to install a Problem Temporary Fix (PTF) into a production system. The packages provided by SUSE are signed against a special PTF key. However, in contrast to SUSE Linux Enterprise 11, this key is not imported by default on SUSE Linux Enterprise 12 systems. To manually import the key, use the following command:

tux > sudo rpm --import \
/usr/share/doc/packages/suse-build-key/suse_ptf_key.asc

After importing the key, you can install PTF packages on your system.

6.2.2 Managing Packages: Install, Update, and Uninstall

Normally, the installation of an RPM archive is quite simple: rpm -i PACKAGE.rpm. With this command the package is installed, but only if its dependencies are fulfilled and if there are no conflicts with other packages. With an error message, rpm requests those packages that need to be installed to meet dependency requirements. In the background, the RPM database ensures that no conflicts arise—a specific file can only belong to one package. By choosing different options, you can force rpm to ignore these defaults, but this is only for experts. Otherwise, you risk compromising the integrity of the system and possibly jeopardize the ability to update the system.

The options -U or --upgrade and -F or --freshen can be used to update a package (for example, rpm -F PACKAGE.rpm). This command removes the files of the old version and immediately installs the new files. The difference between the two versions is that -U installs packages that previously did not exist in the system, while -F merely updates previously installed packages. When updating, rpm updates configuration files carefully using the following strategy:

  • If a configuration file was not changed by the system administrator, rpm installs the new version of the appropriate file. No action by the system administrator is required.

  • If a configuration file was changed by the system administrator before the update, rpm saves the changed file with the extension .rpmorig or .rpmsave (backup file) and installs the version from the new package. This is done only if the originally installed file and the newer version are different. If this is the case, compare the backup file (.rpmorig or .rpmsave) with the newly installed file and make your changes again in the new file. Afterward, delete all .rpmorig and .rpmsave files to avoid problems with future updates.

  • .rpmnew files appear if the configuration file already exists and if the noreplace label was specified in the .spec file.

Following an update, .rpmsave and .rpmnew files should be removed after comparing them, so they do not obstruct future updates. The .rpmorig extension is assigned if the file has not previously been recognized by the RPM database.

Otherwise, .rpmsave is used. In other words, .rpmorig results from updating from a foreign format to RPM. .rpmsave results from updating from an older RPM to a newer RPM. .rpmnew does not disclose any information to whether the system administrator has made any changes to the configuration file. A list of these files is available in /var/adm/rpmconfigcheck. Some configuration files (like /etc/httpd/httpd.conf) are not overwritten to allow continued operation.

The -U switch is not just an equivalent to uninstalling with the -e option and installing with the -i option. Use -U whenever possible.

To remove a package, enter rpm -e PACKAGE. This command only deletes the package if there are no unresolved dependencies. It is theoretically impossible to delete Tcl/Tk, for example, as long as another application requires it. Even in this case, RPM calls for assistance from the database. If such a deletion is, for whatever reason, impossible (even if no additional dependencies exist), it may be helpful to rebuild the RPM database using the option --rebuilddb.

6.2.3 Delta RPM Packages

Delta RPM packages contain the difference between an old and a new version of an RPM package. Applying a delta RPM onto an old RPM results in a completely new RPM. It is not necessary to have a copy of the old RPM because a delta RPM can also work with an installed RPM. The delta RPM packages are even smaller in size than patch RPMs, which is an advantage when transferring update packages over the Internet. The drawback is that update operations with delta RPMs involved consume considerably more CPU cycles than plain or patch RPMs.

The makedeltarpm and applydelta binaries are part of the delta RPM suite (package deltarpm) and help you create and apply delta RPM packages. With the following commands, you can create a delta RPM called new.delta.rpm. The following command assumes that old.rpm and new.rpm are present:

tux > sudo makedeltarpm old.rpm new.rpm new.delta.rpm

Using applydeltarpm, you can reconstruct the new RPM from the file system if the old package is already installed:

tux > sudo applydeltarpm new.delta.rpm new.rpm

To derive it from the old RPM without accessing the file system, use the -r option:

tux > sudo applydeltarpm -r old.rpm new.delta.rpm new.rpm

See /usr/share/doc/packages/deltarpm/README for technical details.

6.2.4 RPM Queries

With the -q option rpm initiates queries, making it possible to inspect an RPM archive (by adding the option -p) and to query the RPM database of installed packages. Several switches are available to specify the type of information required. See Table 6.1, “The Most Important RPM Query Options”.

Table 6.1: The Most Important RPM Query Options

-i

Package information

-l

File list

-f FILE

Query the package that contains the file FILE (the full path must be specified with FILE)

-s

File list with status information (implies -l)

-d

List only documentation files (implies -l)

-c

List only configuration files (implies -l)

--dump

File list with complete details (to be used with -l, -c, or -d)

--provides

List features of the package that another package can request with --requires

--requires, -R

Capabilities the package requires

--scripts

Installation scripts (preinstall, postinstall, uninstall)

For example, the command rpm -q -i wget displays the information shown in Example 6.2, “rpm -q -i wget.

Example 6.2: rpm -q -i wget
Name        : wget
Version     : 1.14
Release     : 17.1
Architecture: x86_64
Install Date: Mon 30 Jan 2017 14:01:29 CET
Group       : Productivity/Networking/Web/Utilities
Size        : 2046483
License     : GPL-3.0+
Signature   : RSA/SHA256, Thu 08 Dec 2016 07:48:44 CET, Key ID 70af9e8139db7c82
Source RPM  : wget-1.14-17.1.src.rpm
Build Date  : Thu 08 Dec 2016 07:48:34 CET
Build Host  : sheep09
Relocations : (not relocatable)
Packager    : https://www.suse.com/
Vendor      : SUSE LLC <https://www.suse.com/>
URL         : http://www.gnu.org/software/wget/
Summary     : A Tool for Mirroring FTP and HTTP Servers
Description :
Wget enables you to retrieve WWW documents or FTP files from a server.
This can be done in script files or via the command line.
Distribution: SUSE Linux Enterprise 12

The option -f only works if you specify the complete file name with its full path. Provide as many file names as desired. For example:

tux > rpm -q -f /bin/rpm /usr/bin/wget
rpm-4.11.2-15.1.x86_64
wget-1.14-17.1.x86_64

If only part of the file name is known, use a shell script as shown in Example 6.3, “Script to Search for Packages”. Pass the partial file name to the script shown as a parameter when running it.

Example 6.3: Script to Search for Packages
#! /bin/sh
for i in $(rpm -q -a -l | grep $1); do
    echo "\"$i\" is in package:"
    rpm -q -f $i
    echo ""
done

The command rpm -q --changelog PACKAGE displays a detailed list of change information about a specific package, sorted by date.

With the installed RPM database, verification checks can be made. Initiate these with -V, or --verify. With this option, rpm shows all files in a package that have been changed since installation. rpm uses eight character symbols to give some hints about the following changes:

Table 6.2: RPM Verify Options

5

MD5 check sum

S

File size

L

Symbolic link

T

Modification time

D

Major and minor device numbers

U

Owner

G

Group

M

Mode (permissions and file type)

In the case of configuration files, the letter c is printed. For example, for changes to /etc/wgetrc (wget package):

tux > rpm -V wget
S.5....T c /etc/wgetrc

The files of the RPM database are placed in /var/lib/rpm. If the partition /usr has a size of 1 GB, this database can occupy nearly 30 MB, especially after a complete update. If the database is much larger than expected, it is useful to rebuild the database with the option --rebuilddb. Before doing this, make a backup of the old database. The cron script cron.daily makes daily copies of the database (packed with gzip) and stores them in /var/adm/backup/rpmdb. The number of copies is controlled by the variable MAX_RPMDB_BACKUPS (default: 5) in /etc/sysconfig/backup. The size of a single backup is approximately 1 MB for 1 GB in /usr.

6.2.5 Installing and Compiling Source Packages

All source packages carry a .src.rpm extension (source RPM).

Note
Note: Installed Source Packages

Source packages can be copied from the installation medium to the hard disk and unpacked with YaST. They are not, however, marked as installed ([i]) in the package manager. This is because the source packages are not entered in the RPM database. Only installed operating system software is listed in the RPM database. When you install a source package, only the source code is added to the system.

The following directories must be available for rpm and rpmbuild in /usr/src/packages (unless you specified custom settings in a file like /etc/rpmrc):

SOURCES

for the original sources (.tar.bz2 or .tar.gz files, etc.) and for distribution-specific adjustments (mostly .diff or .patch files)

SPECS

for the .spec files, similar to a meta Makefile, which control the build process

BUILD

all the sources are unpacked, patched and compiled in this directory

RPMS

where the completed binary packages are stored

SRPMS

here are the source RPMs

When you install a source package with YaST, all the necessary components are installed in /usr/src/packages: the sources and the adjustments in SOURCES and the relevant .spec file in SPECS.

Warning
Warning: System Integrity

Do not experiment with system components (glibc, rpm, etc.), because this endangers the stability of your system.

The following example uses the wget.src.rpm package. After installing the source package, you should have files similar to those in the following list:

/usr/src/packages/SOURCES/wget-1.11.4.tar.bz2
/usr/src/packages/SOURCES/wgetrc.patch
/usr/src/packages/SPECS/wget.spec

rpmbuild -bX /usr/src/packages/SPECS/wget.spec starts the compilation. X is a wild card for various stages of the build process (see the output of --help or the RPM documentation for details). The following is merely a brief explanation:

-bp

Prepare sources in /usr/src/packages/BUILD: unpack and patch.

-bc

Do the same as -bp, but with additional compilation.

-bi

Do the same as -bp, but with additional installation of the built software. Caution: if the package does not support the BuildRoot feature, you might overwrite configuration files.

-bb

Do the same as -bi, but with the additional creation of the binary package. If the compile was successful, the binary should be in /usr/src/packages/RPMS.

-ba

Do the same as -bb, but with the additional creation of the source RPM. If the compilation was successful, the binary should be in /usr/src/packages/SRPMS.

--short-circuit

Skip some steps.

The binary RPM created can now be installed with rpm -i or, preferably, with rpm -U. Installation with rpm makes it appear in the RPM database.

Keep in mind, the BuildRoot directive in the spec file is deprecated since SUSE Linux Enterprise Server 12. If you still need this feature, use the --buildroot option as a workaround.For a more detailed background, see the support database at https://www.suse.com/support/kb/doc?id=7017104.

6.2.6 Compiling RPM Packages with build

The danger with many packages is that unwanted files are added to the running system during the build process. To prevent this use build, which creates a defined environment in which the package is built. To establish this chroot environment, the build script must be provided with a complete package tree. This tree can be made available on the hard disk, via NFS, or from DVD. Set the position with build --rpms DIRECTORY. Unlike rpm, the build command looks for the .spec file in the source directory. To build wget (like in the above example) with the DVD mounted in the system under /media/dvd, use the following commands as root:

root # cd /usr/src/packages/SOURCES/
root # mv ../SPECS/wget.spec .
root # build --rpms /media/dvd/suse/ wget.spec

Subsequently, a minimum environment is established at /var/tmp/build-root. The package is built in this environment. Upon completion, the resulting packages are located in /var/tmp/build-root/usr/src/packages/RPMS.

The build script offers several additional options. For example, cause the script to prefer your own RPMs, omit the initialization of the build environment or limit the rpm command to one of the above-mentioned stages. Access additional information with build --help and by reading the build man page.

6.2.7 Tools for RPM Archives and the RPM Database

Midnight Commander (mc) can display the contents of RPM archives and copy parts of them. It represents archives as virtual file systems, offering all usual menu options of Midnight Commander. Display the HEADER with F3. View the archive structure with the cursor keys and Enter. Copy archive components with F5.

A full-featured package manager is available as a YaST module. For details, see Chapter 13, Installing or Removing Software.

7 System Recovery and Snapshot Management with Snapper

  • Filename: snapper.xml
  • ID: cha.snapper
Abstract

Being able to do file system snapshots providing the ability to do rollbacks on Linux is a feature that was often requested in the past. Snapper, with the Btrfs file system or thin-provisioned LVM volumes now fills that gap.

Btrfs, a new copy-on-write file system for Linux, supports file system snapshots (a copy of the state of a subvolume at a certain point of time) of subvolumes (one or more separately mountable file systems within each physical partition). Snapshots are also supported on thin-provisioned LVM volumes formatted with XFS, Ext4 or Ext3. Snapper lets you create and manage these snapshots. It comes with a command line and a YaST interface. Starting with SUSE Linux Enterprise Server 12 it is also possible to boot from Btrfs snapshots—see Section 7.3, “System Rollback by Booting from Snapshots” for more information.

Using Snapper you can perform the following tasks:

7.1 Default Setup

Snapper on SUSE Linux Enterprise Server is set up to serve as an undo and recovery tool for system changes. By default, the root partition (/) of SUSE Linux Enterprise Server is formatted with Btrfs. Taking snapshots is automatically enabled if the root partition (/) is big enough (approximately more than 16 GB). Taking snapshots on partitions other than / is not enabled by default.

Tip
Tip: Enabling Snapper in the Installed System

If you disabled Snapper during the installation, you can enable it at any time later. To do so, create a default Snapper configuration for the root file system by running

tux > sudo snapper -c root create-config /

Afterward enable the different snapshot types as described in Section 7.1.3.1, “Disabling/Enabling Snapshots”.

Keep in mind that snapshots require a Btrfs root file system with subvolumes set up as proposed by the installer and a partition size of at least 16 GB.

When a snapshot is created, both the snapshot and the original point to the same blocks in the file system. So, initially a snapshot does not occupy additional disk space. If data in the original file system is modified, changed data blocks are copied while the old data blocks are kept for the snapshot. Therefore, a snapshot occupies the same amount of space as the data modified. So, over time, the amount of space a snapshot allocates, constantly grows. As a consequence, deleting files from a Btrfs file system containing snapshots may not free disk space!

Note
Note: Snapshot Location

Snapshots always reside on the same partition or subvolume on which the snapshot has been taken. It is not possible to store snapshots on a different partition or subvolume.

As a result, partitions containing snapshots need to be larger than normal partitions. The exact amount strongly depends on the number of snapshots you keep and the amount of data modifications. As a rule of thumb you should consider using twice the size than you normally would. To prevent disks from running out of space, old snapshots are automatically cleaned up. Refer to Section 7.1.3.4, “Controlling Snapshot Archiving” for details.

7.1.1 Types of Snapshots

Although snapshots themselves do not differ in a technical sense, we distinguish between three types of snapshots, based on the events that trigger them:

Timeline Snapshots

A single snapshot is created every hour. Old snapshots are automatically deleted. By default, the first snapshot of the last ten days, months, and years are kept. Timeline snapshots are disabled by default.

Installation Snapshots

Whenever one or more packages are installed with YaST or Zypper, a pair of snapshots is created: one before the installation starts (Pre) and another one after the installation has finished (Post). In case an important system component such as the kernel has been installed, the snapshot pair is marked as important (important=yes). Old snapshots are automatically deleted. By default the last ten important snapshots and the last ten regular (including administration snapshots) snapshots are kept. Installation snapshots are enabled by default.

Administration Snapshots

Whenever you administrate the system with YaST, a pair of snapshots is created: one when a YaST module is started (Pre) and another when the module is closed (Post). Old snapshots are automatically deleted. By default the last ten important snapshots and the last ten regular snapshots (including installation snapshots) are kept. Administration snapshots are enabled by default.

7.1.2 Directories That Are Excluded from Snapshots

Some directories need to be excluded from snapshots for different reasons. The following list shows all directories that are excluded:

/boot/grub2/i386-pc, /boot/grub2/x86_64-efi, /boot/grub2/powerpc-ieee1275, /boot/grub2/s390x-emu

A rollback of the boot loader configuration is not supported. The directories listed above are architecture-specific. The first two directories are present on AMD64/Intel 64 machines, the latter two on IBM POWER and on IBM z Systems, respectively.

/home

If /home does not reside on a separate partition, it is excluded to avoid data loss on rollbacks.

/opt, /var/opt

Third-party products usually get installed to /opt. It is excluded to avoid uninstalling these applications on rollbacks.

/srv

Contains data for Web and FTP servers. It is excluded to avoid data loss on rollbacks.

/tmp, /var/tmp, /var/cache, /var/crash

All directories containing temporary files and caches are excluded from snapshots.

/usr/local

This directory is used when manually installing software. It is excluded to avoid uninstalling these installations on rollbacks.

/var/lib/libvirt/images

The default location for virtual machine images managed with libvirt. Excluded to ensure virtual machine images are not replaced with older versions during a rollback. By default, this subvolume is created with the option no copy on write.

/var/lib/mailman, /var/spool

Directories containing mails or mail queues are excluded to avoid a loss of mails after a rollback.

/var/lib/named

Contains zone data for the DNS server. Excluded from snapshots to ensure a name server can operate after a rollback.

/var/lib/mariadb, /var/lib/mysql, /var/lib/pgqsl

These directories contain database data. By default, these subvolumes are created with the option no copy on write.

/var/log

Log file location. Excluded from snapshots to allow log file analysis after the rollback of a broken system.

7.1.3 Customizing the Setup

SUSE Linux Enterprise Server comes with a reasonable default setup, which should be sufficient for most use cases. However, all aspects of taking automatic snapshots and snapshot keeping can be configured according to your needs.

7.1.3.1 Disabling/Enabling Snapshots

Each of the three snapshot types (timeline, installation, administration) can be enabled or disabled independently.

Disabling/Enabling Timeline Snapshots

Enabling.  snapper-c root set-config "TIMELINE_CREATE=yes"

Disabling.  snapper -c root set-config "TIMELINE_CREATE=no"

Timeline snapshots are enabled by default, except for the root partition.

Disabling/Enabling Installation Snapshots

Enabling:  Install the package snapper-zypp-plugin

Disabling:  Uninstall the package snapper-zypp-plugin

Installation snapshots are enabled by default.

Disabling/Enabling Administration Snapshots

Enabling:  Set USE_SNAPPER to yes in /etc/sysconfig/yast2.

Disabling:  Set USE_SNAPPER to no in /etc/sysconfig/yast2.

Administration snapshots are enabled by default.

7.1.3.2 Controlling Installation Snapshots

Taking snapshot pairs upon installing packages with YaST or Zypper is handled by the snapper-zypp-plugin. An XML configuration file, /etc/snapper/zypp-plugin.conf defines, when to make snapshots. By default the file looks like the following:

 1 <?xml version="1.0" encoding="utf-8"?>
 2 <snapper-zypp-plugin-conf>
 3  <solvables>
 4   <solvable match="w"1 important="true"2>kernel-*3</solvable>
 5   <solvable match="w" important="true">dracut</solvable>
 6   <solvable match="w" important="true">glibc</solvable>
 7   <solvable match="w" important="true">systemd*</solvable>
 8   <solvable match="w" important="true">udev</solvable>
 9   <solvable match="w">*</solvable>4
10  </solvables>
11 </snapper-zypp-plugin-conf>

1

The match attribute defines whether the pattern is a Unix shell-style wild card (w) or a Python regular expression (re).

2

If the given pattern matches and the corresponding package is marked as important (for example kernel packages), the snapshot will also be marked as important.

3

Pattern to match a package name. Based on the setting of the match attribute, special characters are either interpreted as shell wild cards or regular expressions. This pattern matches all package names starting with kernel-.

4

This line unconditionally matches all packages.

With this configuration snapshot, pairs are made whenever a package is installed (line 9). When the kernel, dracut, glibc, systemd, or udev packages marked as important are installed, the snapshot pair will also be marked as important (lines 4 to 8). All rules are evaluated.

To disable a rule, either delete it or deactivate it using XML comments. To prevent the system from making snapshot pairs for every package installation for example, comment line 9:

 1 <?xml version="1.0" encoding="utf-8"?>
 2 <snapper-zypp-plugin-conf>
 3  <solvables>
 4   <solvable match="w" important="true">kernel-*</solvable>
 5   <solvable match="w" important="true">dracut</solvable>
 6   <solvable match="w" important="true">glibc</solvable>
 7   <solvable match="w" important="true">systemd*</solvable>
 8   <solvable match="w" important="true">udev</solvable>
 9   <!-- <solvable match="w">*</solvable> -->
10  </solvables>
11 </snapper-zypp-plugin-conf>

7.1.3.3 Creating and Mounting New Subvolumes

Creating a new subvolume underneath the / hierarchy and permanently mounting it is supported. Such a subvolume will be excluded from snapshots. You need to make sure not to create it inside an existing snapshot, since you would not be able to delete snapshots anymore after a rollback.

SUSE Linux Enterprise Server is configured with the /@/ subvolume which serves as an independent root for permanent subvolumes such as /opt, /srv, /home and others. Any new subvolumes you create and permanently mount need to be created in this initial root file system.

To do so, run the following commands. In this example, a new subvolume /usr/important is created from /dev/sda2.

tux > sudo mount /dev/sda2 -o subvol=@ /mnt
tux > sudo btrfs subvolume create /mnt/usr/important
tux > sudo umount /mnt

The corresponding entry in /etc/fstab needs to look like the following:

/dev/sda2 /usr/important btrfs subvol=@/usr/important 0 0
Tip
Tip: Disable Copy-On-Write (cow)

A subvolume may contain files that constantly change, such as virtualized disk images, database files, or log files. If so, consider disabling the copy-on-write feature for this volume, to avoid duplication of disk blocks. Use the nodatacow mount option in /etc/fstab to do so:

/dev/sda2 /usr/important btrfs nodatacow,subvol=@/usr/important 0 0

To alternatively disable copy-on-write for single files or directories, use the command chattr +C PATH.

7.1.3.4 Controlling Snapshot Archiving

Snapshots occupy disk space. To prevent disks from running out of space and thus causing system outages, old snapshots are automatically deleted. By default, up to ten important installation and administration snapshots and up to ten regular installation and administration snapshots are kept. If these snapshots occupy more than 50% of the root file system size, additional snapshots will be deleted. A minimum of four important and two regular snapshots are always kept.

Refer to Section 7.4.1, “Managing Existing Configurations” for instructions on how to change these values.

7.1.3.5 Using Snapper on Thin-Provisioned LVM Volumes

Apart from snapshots on Btrfs file systems, Snapper also supports taking snapshots on thin-provisioned LVM volumes (snapshots on regular LVM volumes are not supported) formatted with XFS, Ext4 or Ext3. For more information and setup instructions on LVM volumes, refer to Section 12.2, “LVM Configuration”.

To use Snapper on a thin-provisioned LVM volume you need to create a Snapper configuration for it. On LVM it is required to specify the file system with --fstype=lvm(FILESYSTEM). ext3, etx4 or xfs are valid values for FILESYSTEM. Example:

tux > sudo snapper -c lvm create-config --fstype="lvm(xfs)" /thin_lvm

You can adjust this configuration according to your needs as described in Section 7.4.1, “Managing Existing Configurations”.

7.2 Using Snapper to Undo Changes

Snapper on SUSE Linux Enterprise Server is preconfigured to serve as a tool that lets you undo changes made by zypper and YaST. For this purpose, Snapper is configured to create a pair of snapshots before and after each run of zypper and YaST. Snapper also lets you restore system files that have been accidentally deleted or modified. Timeline snapshots for the root partition need to be enabled for this purpose—see Section 7.1.3.1, “Disabling/Enabling Snapshots” for details.

By default, automatic snapshots as described above are configured for the root partition and its subvolumes. To make snapshots available for other partitions such as /home for example, you can create custom configurations.

Important
Important: Undoing Changes Compared to Rollback

When working with snapshots to restore data, it is important to know that there are two fundamentally different scenarios Snapper can handle:

Undoing Changes

When undoing changes as described in the following, two snapshots are being compared and the changes between these two snapshots are made undone. Using this method also allows to explicitly select the files that should be restored.

Rollback

When doing rollbacks as described in Section 7.3, “System Rollback by Booting from Snapshots”, the system is reset to the state at which the snapshot was taken.

When undoing changes, it is also possible to compare a snapshot against the current system. When restoring all files from such a comparison, this will have the same result as doing a rollback. However, using the method described in Section 7.3, “System Rollback by Booting from Snapshots” for rollbacks should be preferred, since it is faster and allows you to review the system before doing the rollback.

Warning
Warning: Data Consistency

There is no mechanism to ensure data consistency when creating a snapshot. Whenever a file (for example, a database) is written at the same time as the snapshot is being created, it will result in a corrupted or partly written file. Restoring such a file will cause problems. Furthermore, some system files such as /etc/mtab must never be restored. Therefore it is strongly recommended to always closely review the list of changed files and their diffs. Only restore files that really belong to the action you want to revert.

7.2.1 Undoing YaST and Zypper Changes

If you set up the root partition with Btrfs during the installation, Snapper—preconfigured for doing rollbacks of YaST or Zypper changes—will automatically be installed. Every time you start a YaST module or a Zypper transaction, two snapshots are created: a pre-snapshot capturing the state of the file system before the start of the module and a post-snapshot after the module has been finished.

Using the YaST Snapper module or the snapper command line tool, you can undo the changes made by YaST/Zypper by restoring files from the pre-snapshot. Comparing two snapshots the tools also allow you to see which files have been changed. You can also display the differences between two versions of a file (diff).

Procedure 7.1: Undoing Changes Using the YaST Snapper Module
  1. Start the Snapper module from the Miscellaneous section in YaST or by entering yast2 snapper.

  2. Make sure Current Configuration is set to root. This is always the case unless you have manually added own Snapper configurations.

  3. Choose a pair of pre- and post-snapshots from the list. Both, YaST and Zypper snapshot pairs are of the type Pre & Post. YaST snapshots are labeled as zypp(y2base) in the Description column; Zypper snapshots are labeled zypp(zypper).

  4. Click Show Changes to open the list of files that differ between the two snapshots.

  5. Review the list of files. To display a diff between the pre- and post-version of a file, select it from the list.

  6. To restore one or more files, select the relevant files or directories by activating the respective check box. Click Restore Selected and confirm the action by clicking Yes.

    To restore a single file, activate its diff view by clicking its name. Click Restore From First and confirm your choice with Yes.

Procedure 7.2: Undoing Changes Using the snapper Command
  1. Get a list of YaST and Zypper snapshots by running snapper list -t pre-post. YaST snapshots are labeled as yast MODULE_NAME in the Description column; Zypper snapshots are labeled zypp(zypper).

    tux > sudo snapper list -t pre-post
    Pre # | Post # | Pre Date                      | Post Date                     | Description
    ------+--------+-------------------------------+-------------------------------+--------------
    311   | 312    | Tue 06 May 2014 14:05:46 CEST | Tue 06 May 2014 14:05:52 CEST | zypp(y2base)
    340   | 341    | Wed 07 May 2014 16:15:10 CEST | Wed 07 May 2014 16:15:16 CEST | zypp(zypper)
    342   | 343    | Wed 07 May 2014 16:20:38 CEST | Wed 07 May 2014 16:20:42 CEST | zypp(y2base)
    344   | 345    | Wed 07 May 2014 16:21:23 CEST | Wed 07 May 2014 16:21:24 CEST | zypp(zypper)
    346   | 347    | Wed 07 May 2014 16:41:06 CEST | Wed 07 May 2014 16:41:10 CEST | zypp(y2base)
    348   | 349    | Wed 07 May 2014 16:44:50 CEST | Wed 07 May 2014 16:44:53 CEST | zypp(y2base)
    350   | 351    | Wed 07 May 2014 16:46:27 CEST | Wed 07 May 2014 16:46:38 CEST | zypp(y2base)
  2. Get a list of changed files for a snapshot pair with snapper status PRE..POST. Files with content changes are marked with c, files that have been added are marked with + and deleted files are marked with -.

    tux > sudo snapper status 350..351
    +..... /usr/share/doc/packages/mikachan-fonts
    +..... /usr/share/doc/packages/mikachan-fonts/COPYING
    +..... /usr/share/doc/packages/mikachan-fonts/dl.html
    c..... /usr/share/fonts/truetype/fonts.dir
    c..... /usr/share/fonts/truetype/fonts.scale
    +..... /usr/share/fonts/truetype/みかちゃん-p.ttf
    +..... /usr/share/fonts/truetype/みかちゃん-pb.ttf
    +..... /usr/share/fonts/truetype/みかちゃん-ps.ttf
    +..... /usr/share/fonts/truetype/みかちゃん.ttf
    c..... /var/cache/fontconfig/7ef2298fde41cc6eeb7af42e48b7d293-x86_64.cache-4
    c..... /var/lib/rpm/Basenames
    c..... /var/lib/rpm/Dirnames
    c..... /var/lib/rpm/Group
    c..... /var/lib/rpm/Installtid
    c..... /var/lib/rpm/Name
    c..... /var/lib/rpm/Packages
    c..... /var/lib/rpm/Providename
    c..... /var/lib/rpm/Requirename
    c..... /var/lib/rpm/Sha1header
    c..... /var/lib/rpm/Sigmd5
  3. To display the diff for a certain file, run snapper diff PRE..POST FILENAME. If you do not specify FILENAME, a diff for all files will be displayed.

    tux > sudo snapper diff 350..351 /usr/share/fonts/truetype/fonts.scale
    --- /.snapshots/350/snapshot/usr/share/fonts/truetype/fonts.scale       2014-04-23 15:58:57.000000000 +0200
    +++ /.snapshots/351/snapshot/usr/share/fonts/truetype/fonts.scale       2014-05-07 16:46:31.000000000 +0200
    @@ -1,4 +1,4 @@
    -1174
    +1486
     ds=y:ai=0.2:luximr.ttf -b&h-luxi mono-bold-i-normal--0-0-0-0-c-0-iso10646-1
     ds=y:ai=0.2:luximr.ttf -b&h-luxi mono-bold-i-normal--0-0-0-0-c-0-iso8859-1
    [...]
  4. To restore one or more files run snapper -v undochange PRE..POST FILENAMES. If you do not specify a FILENAMES, all changed files will be restored.

    tux > sudo snapper -v undochange 350..351
         create:0 modify:13 delete:7
         undoing change...
         deleting /usr/share/doc/packages/mikachan-fonts
         deleting /usr/share/doc/packages/mikachan-fonts/COPYING
         deleting /usr/share/doc/packages/mikachan-fonts/dl.html
         deleting /usr/share/fonts/truetype/みかちゃん-p.ttf
         deleting /usr/share/fonts/truetype/みかちゃん-pb.ttf
         deleting /usr/share/fonts/truetype/みかちゃん-ps.ttf
         deleting /usr/share/fonts/truetype/みかちゃん.ttf
         modifying /usr/share/fonts/truetype/fonts.dir
         modifying /usr/share/fonts/truetype/fonts.scale
         modifying /var/cache/fontconfig/7ef2298fde41cc6eeb7af42e48b7d293-x86_64.cache-4
         modifying /var/lib/rpm/Basenames
         modifying /var/lib/rpm/Dirnames
         modifying /var/lib/rpm/Group
         modifying /var/lib/rpm/Installtid
         modifying /var/lib/rpm/Name
         modifying /var/lib/rpm/Packages
         modifying /var/lib/rpm/Providename
         modifying /var/lib/rpm/Requirename
         modifying /var/lib/rpm/Sha1header
         modifying /var/lib/rpm/Sigmd5
         undoing change done
Warning
Warning: Reverting User Additions

Reverting user additions via undoing changes with Snapper is not recommended. Since certain directories are excluded from snapshots, files belonging to these users will remain in the file system. If a user with the same user ID as a deleted user is created, this user will inherit the files. Therefore it is strongly recommended to use the YaST User and Group Management tool to remove users.

7.2.2 Using Snapper to Restore Files

Apart from the installation and administration snapshots, Snapper creates timeline snapshots. You can use these backup snapshots to restore files that have accidentally been deleted or to restore a previous version of a file. By using Snapper's diff feature you can also find out which modifications have been made at a certain point of time.

Being able to restore files is especially interesting for data, which may reside on subvolumes or partitions for which snapshots are not taken by default. To be able to restore files from home directories, for example, create a separate Snapper configuration for /home doing automatic timeline snapshots. See Section 7.4, “Creating and Modifying Snapper Configurations” for instructions.

Warning
Warning: Restoring Files Compared to Rollback

Snapshots taken from the root file system (defined by Snapper's root configuration), can be used to do a system rollback. The recommended way to do such a rollback is to boot from the snapshot and then perform the rollback. See Section 7.3, “System Rollback by Booting from Snapshots” for details.

Performing a rollback would also be possible by restoring all files from a root file system snapshot as described below. However, this is not recommended. You may restore single files, for example a configuration file from the /etc directory, but not the complete list of files from the snapshot.

This restriction only affects snapshots taken from the root file system!

Procedure 7.3: Restoring Files Using the YaST Snapper Module
  1. Start the Snapper module from the Miscellaneous section in YaST or by entering yast2 snapper.

  2. Choose the Current Configuration from which to choose a snapshot.

  3. Select a timeline snapshot from which to restore a file and choose Show Changes. Timeline snapshots are of the type Single with a description value of timeline.

  4. Select a file from the text box by clicking the file name. The difference between the snapshot version and the current system is shown. Activate the check box to select the file for restore. Do so for all files you want to restore.

  5. Click Restore Selected and confirm the action by clicking Yes.

Procedure 7.4: Restoring Files Using the snapper Command
  1. Get a list of timeline snapshots for a specific configuration by running the following command:

    tux > sudo snapper -c CONFIG list -t single | grep timeline

    CONFIG needs to be replaced by an existing Snapper configuration. Use snapper list-configs to display a list.

  2. Get a list of changed files for a given snapshot by running the following command:

    tux > sudo snapper -c CONFIG status SNAPSHOT_ID..0

    Replace SNAPSHOT_ID by the ID for the snapshot from which you want to restore the file(s).

  3. Optionally list the differences between the current file version and the one from the snapshot by running

    tux > sudo snapper -c CONFIG diff SNAPSHOT_ID..0 FILE NAME

    If you do not specify <FILE NAME>, the difference for all files are shown.

  4. To restore one or more files, run

    tux > sudo snapper -c CONFIG -v undochange SNAPSHOT_ID..0 FILENAME1 FILENAME2

    If you do not specify file names, all changed files will be restored.

7.3 System Rollback by Booting from Snapshots

The GRUB 2 version included on SUSE Linux Enterprise Server can boot from Btrfs snapshots. Together with Snapper's rollback feature, this allows to recover a misconfigured system. Only snapshots created for the default Snapper configuration (root) are bootable.

Important
Important: Supported Configuration

As of SUSE Linux Enterprise Server 12 SP3 system rollbacks are only supported if the default subvolume configuration of the root partition has not been changed.

When booting a snapshot, the parts of the file system included in the snapshot are mounted read-only; all other file systems and parts that are excluded from snapshots are mounted read-write and can be modified.

Important
Important: Undoing Changes Compared to Rollback

When working with snapshots to restore data, it is important to know that there are two fundamentally different scenarios Snapper can handle:

Undoing Changes

When undoing changes as described in Section 7.2, “Using Snapper to Undo Changes”, two snapshots are compared and the changes between these two snapshots are reverted. Using this method also allows to explicitly exclude selected files from being restored.

Rollback

When doing rollbacks as described in the following, the system is reset to the state at which the snapshot was taken.

To do a rollback from a bootable snapshot, the following requirements must be met. When doing a default installation, the system is set up accordingly.

Requirements for a Rollback from a Bootable Snapshot
  • The root file system needs to be Btrfs. Booting from LVM volume snapshots is not supported.

  • The root file system needs to be on a single device, a single partition and a single subvolume. Directories that are excluded from snapshots such as /srv (see Section 7.1.2, “Directories That Are Excluded from Snapshots” for a full list) may reside on separate partitions.

  • The system needs to be bootable via the installed boot loader.

To perform a rollback from a bootable snapshot, do as follows:

  1. Boot the system. In the boot menu choose Bootable snapshots and select the snapshot you want to boot. The list of snapshots is listed by date—the most recent snapshot is listed first.

  2. Log in to the system. Carefully check whether everything works as expected. Note that you cannot write to any directory that is part of the snapshot. Data you write to other directories will not get lost, regardless of what you do next.

  3. Depending on whether you want to perform the rollback or not, choose your next step:

    1. If the system is in a state where you do not want to do a rollback, reboot to boot into the current system state. You can then choose a different snapshot, or start the rescue system.

    2. To perform the rollback, run

      tux > sudo snapper rollback

      and reboot afterward. On the boot screen, choose the default boot entry to reboot into the reinstated system. A snapshot of the file system status before the rollback is created. The default subvolume for root will be replaced with a fresh read-write snapshot. For details, see Section 7.3.1, “Snapshots after Rollback”.

      It is useful to add a description for the snapshot with the -d option. For example:

      New file system root since rollback on DATE TIME
Tip
Tip: Rolling Back to a Specific Installation State

If snapshots are not disabled during installation, an initial bootable snapshot is created at the end of the initial system installation. You can go back to that state at any time by booting this snapshot. The snapshot can be identified by the description after installation.

A bootable snapshot is also created when starting a system upgrade to a service pack or a new major release (provided snapshots are not disabled).

7.3.1 Snapshots after Rollback

Before a rollback is performed, a snapshot of the running file system is created. The description references the ID of the snapshot that was restored in the rollback.

Snapshots created by rollbacks receive the value number for the Cleanup attribute. The rollback snapshots are therefore automatically deleted when the set number of snapshots is reached. Refer to Section 7.6, “Automatic Snapshot Clean-Up” for details. If the snapshot contains important data, extract the data from the snapshot before it is removed.

7.3.1.1 Example of Rollback Snapshot

For example, after a fresh installation the following snapshots are available on the system:

root # snapper --iso list
Type   | # |     | Cleanup | Description           | Userdata
-------+---+ ... +---------+-----------------------+--------------
single | 0 |     |         | current               |
single | 1 |     |         | first root filesystem |
single | 2 |     | number  | after installation    | important=yes

After running sudo snapper rollback snapshot 3 is created and contains the state of the system before the rollback was executed. Snapshot 4 is the new default Btrfs subvolume and thus the system after a reboot.

root # snapper --iso list
Type   | # |     | Cleanup | Description           | Userdata
-------+---+ ... +---------+-----------------------+--------------
single | 0 |     |         | current               |
single | 1 |     | number  | first root filesystem |
single | 2 |     | number  | after installation    | important=yes
single | 3 |     | number  | rollback backup of #1 | important=yes
single | 4 |     |         |                       |

7.3.2 Accessing and Identifying Snapshot Boot Entries

To boot from a snapshot, reboot your machine and choose Start Bootloader from a read-only snapshot. A screen listing all bootable snapshots opens. The most recent snapshot is listed first, the oldest last. Use the keys and to navigate and press Enter to activate the selected snapshot. Activating a snapshot from the boot menu does not reboot the machine immediately, but rather opens the boot loader of the selected snapshot.

Boot Loader: Snapshots
Figure 7.1: Boot Loader: Snapshots

Each snapshot entry in the boot loader follows a naming scheme which makes it possible to identify it easily:

[*]1OS2 (KERNEL3,DATE4TTIME5,DESCRIPTION6)

1

If the snapshot was marked important, the entry is marked with a *.

2

Operating system label.

4

Date in the format YYYY-MM-DD.

5

Time in the format HH:MM.

6

This field contains a description of the snapshot. In case of a manually created snapshot this is the string created with the option --description or a custom string (see Tip: Setting a Custom Description for Boot Loader Snapshot Entries). In case of an automatically created snapshot, it is the tool that was called, for example zypp(zypper) or yast_sw_single. Long descriptions may be truncated, depending on the size of the boot screen.

Tip
Tip: Setting a Custom Description for Boot Loader Snapshot Entries

It is possible to replace the default string in the description field of a snapshot with a custom string. This is for example useful if an automatically created description is not sufficient, or a user-provided description is too long. To set a custom string STRING for snapshot NUMBER, use the following command:

tux > sudo snapper modify --userdata "bootloader=STRING" NUMBER

The description should be no longer than 25 characters—everything that exceeds this size will not be readable on the boot screen.

7.3.3 Limitations

A complete system rollback, restoring the complete system to the identical state as it was in when a snapshot was taken, is not possible.

7.3.3.1 Directories Excluded from Snapshots

Root file system snapshots do not contain all directories. See Section 7.1.2, “Directories That Are Excluded from Snapshots” for details and reasons. As a general consequence, data from these directories is not restored, resulting in the following limitations.

Add-ons and Third Party Software may be Unusable after a Rollback

Applications and add-ons installing data in subvolumes excluded from the snapshot, such as /opt, may not work after a rollback, if others parts of the application data are also installed on subvolumes included in the snapshot. Re-install the application or the add-on to solve this problem.

File Access Problems

If an application had changed file permissions and/or ownership in between snapshot and current system, the application may not be able to access these files. Reset permissions and/or ownership for the affected files after the rollback.

Incompatible Data Formats

If a service or an application has established a new data format in between snapshot and current system, the application may not be able to read the affected data files after a rollback.

Subvolumes with a Mixture of Code and Data

Subvolumes like /srv may contain a mixture of code and data. A rollback may result in non-functional code. A downgrade of the PHP version, for example, may result in broken PHP scripts for the Web server.

User Data

If a rollback removes users from the system, data that is owned by these users in directories excluded from the snapshot, is not removed. If a user with the same user ID is created, this user will inherit the files. Use a tool like find to locate and remove orphaned files.

7.3.3.2 No Rollback of Boot Loader Data

A rollback of the boot loader is not possible, since all stages of the boot loader must fit together. This cannot be guaranteed when doing rollbacks of /boot.

7.4 Creating and Modifying Snapper Configurations

The way Snapper behaves is defined in a configuration file that is specific for each partition or Btrfs subvolume. These configuration files reside under /etc/snapper/configs/.

In case the root file system is big enough (approximately 12 GB), snapshots are automatically enabled for the root file system / upon installation. The corresponding default configuration is named root. It creates and manages the YaST and Zypper snapshot. See Section 7.4.1.1, “Configuration Data” for a list of the default values.

Note
Note: Minimum Root File System Size for Enabling Snapshots

As explained in Section 7.1, “Default Setup”, enabling snapshots requires additional free space in the root file system. The amount depends on the amount of packages installed and the amount of changes made to the volume that is included in snapshots. The snapshot frequency and the number of snapshots that get archived also matter.

There is a minimum root file system size that is required in order to automatically enable snapshots during the installation. As of SUSE Linux Enterprise Server 12 SP3 this size is approximately 12 GB. This value may change in the future, depending on architecture and the size of the base system. It depends on the values for the following tags in the file /control.xml from the installation media:

<root_base_size>
<btrfs_increase_percentage>

It is calculated with the following formula: ROOT_BASE_SIZE * (1 + BTRFS_INCREASE_PERCENTAGE/100)

Keep in mind that this value is a minimum size. Consider using more space for the root file system. As a rule of thumb, double the size you would use when not having enabled snapshots.

You may create your own configurations for other partitions formatted with Btrfs or existing subvolumes on a Btrfs partition. In the following example we will set up a Snapper configuration for backing up the Web server data residing on a separate, Btrfs-formatted partition mounted at /srv/www.

After a configuration has been created, you can either use snapper itself or the YaST Snapper module to restore files from these snapshots. In YaST you need to select your Current Configuration, while you need to specify your configuration for snapper with the global switch -c (for example, snapper -c myconfig list).

To create a new Snapper configuration, run snapper create-config:

tux > sudo snapper -c www-data1 create-config /srv/www2

1

Name of configuration file.

2

Mount point of the partition or Btrfs subvolume on which to take snapshots.

This command will create a new configuration file /etc/snapper/configs/www-data with reasonable default values (taken from /etc/snapper/config-templates/default). Refer to Section 7.4.1, “Managing Existing Configurations” for instructions on how to adjust these defaults.

Tip
Tip: Configuration Defaults

Default values for a new configuration are taken from /etc/snapper/config-templates/default. To use your own set of defaults, create a copy of this file in the same directory and adjust it to your needs. To use it, specify the -t option with the create-config command:

tux > sudo snapper -c www-data create-config -t MY_DEFAULTS /srv/www

7.4.1 Managing Existing Configurations

The snapper offers several subcommands for managing existing configurations. You can list, show, delete and modify them:

List Configurations

Use the command snapper list-configs to get all existing configurations:

tux > sudo snapper list-configs
Config | Subvolume
-------+----------
root   | /
usr    | /usr
local  | /local
Show a Configuration

Use the subcommand snapper -c CONFIG get-config to display the specified configuration. Config needs to be replaced by a configuration name shown by snapper list-configs. See Section 7.4.1.1, “Configuration Data” for more information on the configuration options.

To display the default configuration run

tux > sudo snapper -c root get-config
Modify a Configuration

Use the subcommand snapper -c CONFIG set-config OPTION=VALUE to modify an option in the specified configuration. Config needs to be replaced by a configuration name shown by snapper list-configs. Possible values for OPTION and VALUE are listed in Section 7.4.1.1, “Configuration Data”.

Delete a Configuration

Use the subcommand snapper -c CONFIG delete-config to delete a configuration. Config needs to be replaced by a configuration name shown by snapper list-configs.

7.4.1.1 Configuration Data

Each configuration contains a list of options that can be modified from the command line. The following list provides details for each option. To change a value, run snapper -c CONFIG set-config "KEY=VALUE".

ALLOW_GROUPS, ALLOW_USERS

Granting permissions to use snapshots to regular users. See Section 7.4.1.2, “Using Snapper as Regular User” for more information.

The default value is "".

BACKGROUND_COMPARISON

Defines whether pre and post snapshots should be compared in the background after creation.

The default value is "yes".

EMPTY_*

Defines the clean-up algorithm for snapshots pairs with identical pre and post snapshots. See Section 7.6.3, “Cleaning Up Snapshot Pairs That Do Not Differ” for details.

FSTYPE

File system type of the partition. Do not change.

The default value is "btrfs".

NUMBER_*

Defines the clean-up algorithm for installation and admin snapshots. See Section 7.6.1, “Cleaning Up Numbered Snapshots” for details.

QGROUP / SPACE_LIMIT

Adds quota support to the clean-up algorithms. See Section 7.6.5, “Adding Disk Quota Support” for details.

SUBVOLUME

Mount point of the partition or subvolume to snapshot. Do not change.

The default value is "/".

SYNC_ACL

If Snapper is used by regular users (see Section 7.4.1.2, “Using Snapper as Regular User”), the users must be able to access the .snapshot directories and to read files within them. If SYNC_ACL is set to yes, Snapper automatically makes them accessible using ACLs for users and groups from the ALLOW_USERS or ALLOW_GROUPS entries.

The default value is "no".

TIMELINE_CREATE

If set to yes, hourly snapshots are created. Valid values: yes, no.

The default value is "no".

TIMELINE_CLEANUP / TIMELINE_LIMIT_*

Defines the clean-up algorithm for timeline snapshots. See Section 7.6.2, “Cleaning Up Timeline Snapshots” for details.

7.4.1.2 Using Snapper as Regular User

By default Snapper can only be used by root. However, there are cases in which certain groups or users need to be able to create snapshots or undo changes by reverting to a snapshot:

  • Web site administrators who want to take snapshots of /srv/www

  • Users who want to take a snapshot of their home directory

For these purposes Snapper configurations that grant permissions to users or/and groups can be created. The corresponding .snapshots directory needs to be readable and accessible by the specified users. The easiest way to achieve this is to set the SYNC_ACL option to yes.

Procedure 7.5: Enabling Regular Users to Use Snapper

Note that all steps in this procedure need to be run by root.

  1. If not existing, create a Snapper configuration for the partition or subvolume on which the user should be able to use Snapper. Refer to Section 7.4, “Creating and Modifying Snapper Configurations” for instructions. Example:

    tux > sudo snapper --config web_data create /srv/www
  2. The configuration file is created under /etc/snapper/configs/CONFIG, where CONFIG is the value you specified with -c/--config in the previous step (for example /etc/snapper/configs/web_data). Adjust it according to your needs; see Section 7.4.1, “Managing Existing Configurations” for details.

  3. Set values for ALLOW_USERS and/or ALLOW_GROUPS to grant permissions to users and/or groups, respectively. Multiple entries need to be separated by Space. To grant permissions to the user www_admin for example, run:

    tux > sudo snapper -c web_data set-config "ALLOW_USERS=www_admin" SYNC_ACL="yes"
  4. The given Snapper configuration can now be used by the specified user(s) and/or group(s). You can test it with the list command, for example:

    www_admin:~ > snapper -c web_data list

7.5 Manually Creating and Managing Snapshots

Snapper is not restricted to creating and managing snapshots automatically by configuration; you can also create snapshot pairs (before and after) or single snapshots manually using either the command-line tool or the YaST module.

All Snapper operations are carried out for an existing configuration (see Section 7.4, “Creating and Modifying Snapper Configurations” for details). You can only take snapshots of partitions or volumes for which a configuration exists. By default the system configuration (root) is used. If you want to create or manage snapshots for your own configuration you need to explicitly choose it. Use the Current Configuration drop-down box in YaST or specify the -c on the command line (snapper -c MYCONFIG COMMAND).

7.5.1 Snapshot Metadata

Each snapshot consists of the snapshot itself and some metadata. When creating a snapshot you also need to specify the metadata. Modifying a snapshot means changing its metadata—you cannot modify its content. Use snapper list to show existing snapshots and their metadata:

snapper --config home list

Lists snapshots for the configuration home. To list snapshots for the default configuration (root), use snapper -c root list or snapper list.

snapper list -a

Lists snapshots for all existing configurations.

snapper list -t pre-post

Lists all pre and post snapshot pairs for the default (root) configuration.

snapper list -t single

Lists all snapshots of the type single for the default (root) configuration.

The following metadata is available for each snapshot:

  • Type: Snapshot type, see Section 7.5.1.1, “Snapshot Types” for details. This data cannot be changed.

  • Number: Unique number of the snapshot. This data cannot be changed.

  • Pre Number: Specifies the number of the corresponding pre snapshot. For snapshots of type post only. This data cannot be changed.

  • Description: A description of the snapshot.

  • Userdata: An extended description where you can specify custom data in the form of a comma-separated key=value list: reason=testing, project=foo. This field is also used to mark a snapshot as important (important=yes) and to list the user that created the snapshot (user=tux).

  • Cleanup-Algorithm: Cleanup-algorithm for the snapshot, see Section 7.6, “Automatic Snapshot Clean-Up” for details.

7.5.1.1 Snapshot Types

Snapper knows three different types of snapshots: pre, post, and single. Physically they do not differ, but Snapper handles them differently.

pre

Snapshot of a file system before a modification. Each pre snapshot has got a corresponding post snapshot. Used for the automatic YaST/Zypper snapshots, for example.

post

Snapshot of a file system after a modification. Each post snapshot has got a corresponding pre snapshot. Used for the automatic YaST/Zypper snapshots, for example.

single

Stand-alone snapshot. Used for the automatic hourly snapshots, for example. This is the default type when creating snapshots.

7.5.1.2 Cleanup-algorithms

Snapper provides three algorithms to clean up old snapshots. The algorithms are executed in a daily cron job. It is possible to define the number of different types of snapshots to keep in the Snapper configuration (see Section 7.4.1, “Managing Existing Configurations” for details).

number

Deletes old snapshots when a certain snapshot count is reached.

timeline

Deletes old snapshots having passed a certain age, but keeps several hourly, daily, monthly, and yearly snapshots.

empty-pre-post

Deletes pre/post snapshot pairs with empty diffs.

7.5.2 Creating Snapshots

Creating a snapshot is done by running snapper create or by clicking Create in the YaST module Snapper. The following examples explain how to create snapshots from the command line. It should be easy to adopt them when using the YaST interface.

Tip
Tip: Snapshot Description

You should always specify a meaningful description to later be able to identify its purpose. Even more information can be specified via the user data option.

snapper create --description "Snapshot for week 2 2014"

Creates a stand-alone snapshot (type single) for the default (root) configuration with a description. Because no cleanup-algorithm is specified, the snapshot will never be deleted automatically.

snapper --config home create --description "Cleanup in ~tux"

Creates a stand-alone snapshot (type single) for a custom configuration named home with a description. Because no cleanup-algorithm is specified, the snapshot will never be deleted automatically.

snapper --config home create --description "Daily data backup" --cleanup-algorithm timeline>

Creates a stand-alone snapshot (type single) for a custom configuration named home with a description. The file will automatically be deleted when it meets the criteria specified for the timeline cleanup-algorithm in the configuration.

snapper create --type pre --print-number --description "Before the Apache config cleanup" --userdata "important=yes"

Creates a snapshot of the type pre and prints the snapshot number. First command needed to create a pair of snapshots used to save a before and after state. The snapshot is marked as important.

snapper create --type post --pre-number 30 --description "After the Apache config cleanup" --userdata "important=yes"

Creates a snapshot of the type post paired with the pre snapshot number 30. Second command needed to create a pair of snapshots used to save a before and after state. The snapshot is marked as important.

snapper create --command COMMAND --description "Before and after COMMAND"

Automatically creates a snapshot pair before and after running COMMAND. This option is only available when using snapper on the command line.

7.5.3 Modifying Snapshot Metadata

Snapper allows you to modify the description, the cleanup algorithm, and the user data of a snapshot. All other metadata cannot be changed. The following examples explain how to modify snapshots from the command line. It should be easy to adopt them when using the YaST interface.

To modify a snapshot on the command line, you need to know its number. Use snapper list to display all snapshots and their numbers.

The YaST Snapper module already lists all snapshots. Choose one from the list and click Modify.

snapper modify --cleanup-algorithm "timeline" 10

Modifies the metadata of snapshot 10 for the default (root) configuration. The cleanup algorithm is set to timeline.

snapper --config home modify --description "daily backup" -cleanup-algorithm "timeline" 120

Modifies the metadata of snapshot 120 for a custom configuration named home. A new description is set and the cleanup algorithm is unset.

7.5.4 Deleting Snapshots

To delete a snapshot with the YaST Snapper module, choose a snapshot from the list and click Delete.

To delete a snapshot with the command line tool, you need to know its number. Get it by running snapper list. To delete a snapshot, run snapper delete NUMBER.

Deleting the current default subvolume snapshot is not allowed.

When deleting snapshots with Snapper, the freed space will be claimed by a Btrfs process running in the background. Thus the visibility and the availability of free space is delayed. In case you need space freed by deleting a snapshot to be available immediately, use the option --sync with the delete command.

Tip
Tip: Deleting Snapshot Pairs

When deleting a pre snapshot, you should always delete its corresponding post snapshot (and vice versa).

snapper delete 65

Deletes snapshot 65 for the default (root) configuration.

snapper -c home delete 89 90

Deletes snapshots 89 and 90 for a custom configuration named home.

snapper delete --sync 23

Deletes snapshot 23 for the default (root) configuration and makes the freed space available immediately.

Tip
Tip: Delete Unreferenced Snapshots

Sometimes the Btrfs snapshot is present but the XML file containing the metadata for Snapper is missing. In this case the snapshot is not visible for Snapper and needs to be deleted manually:

btrfs subvolume delete /.snapshots/SNAPSHOTNUMBER/snapshot
rm -rf /.snapshots/SNAPSHOTNUMBER
Tip
Tip: Old Snapshots Occupy More Disk Space

If you delete snapshots to free space on your hard disk, make sure to delete old snapshots first. The older a snapshot is, the more disk space it occupies.

Snapshots are also automatically deleted by a daily cron job. Refer to Section 7.5.1.2, “Cleanup-algorithms” for details.

7.6 Automatic Snapshot Clean-Up

Snapshots occupy disk space and over time the amount of disk space occupied by the snapshots may become large. To prevent disks from running out of space, Snapper offers algorithms to automatically delete old snapshots. These algorithms differentiate between timeline snapshots and numbered snapshots (administration plus installation snapshot pairs). You can specify the number of snapshots to keep for each type.

In addition to that, you can optionally specify a disk space quota, defining the maximum amount of disk space the snapshots may occupy. It is also possible to automatically delete pre and post snapshots pairs that do not differ.

A clean-up algorithm is always bound to a single Snapper configuration, so you need to configure algorithms for each configuration. To prevent certain snapshots from being automatically deleted, refer to How to make a snapshot permanent? .

The default setup (root) is configured to do clean-up for numbered snapshots and empty pre and post snapshot pairs. Quota support is enabled—snapshots may not occupy more than 50% of the available disk space of the root partition. Timeline snapshots are disabled by default, therefore the timeline clean-up algorithm is also disabled.

7.6.1 Cleaning Up Numbered Snapshots

Cleaning up numbered snapshots—administration plus installation snapshot pairs—is controlled by the following parameters of a Snapper configuration.

NUMBER_CLEANUP

Enables or disables clean-up of installation and admin snapshot pairs. If enabled, snapshot pairs are deleted when the total snapshot count exceeds a number specified with NUMBER_LIMIT and/or NUMBER_LIMIT_IMPORTANT and an age specified with NUMBER_MIN_AGE. Valid values: yes (enable), no (disable).

The default value is "yes".

Example command to change or set:

tux > sudo snapper -c CONFIG set-config "NUMBER_CLEANUP=no"
NUMBER_LIMIT / NUMBER_LIMIT_IMPORTANT

Defines how many regular and/or important installation and administration snapshot pairs to keep. Only the youngest snapshots will be kept. Ignored if NUMBER_CLEANUP is set to "no".

The default value is "2-10" for NUMBER_LIMIT and "4-10" for NUMBER_LIMIT_IMPORTANT.

Example command to change or set:

tux > sudo snapper -c CONFIG set-config "NUMBER_LIMIT=10"
Important
Important: Ranged Compared to Constant Values

In case quota support is enabled (see Section 7.6.5, “Adding Disk Quota Support”) the limit needs to be specified as a minimum-maximum range, for example 2-10. If quota support is disabled, a constant value, for example 10, needs to be provided, otherwise cleaning-up will fail with an error.

NUMBER_MIN_AGE

Defines the minimum age in seconds a snapshot must have before it can automatically be deleted. Snapshots younger than the value specified here will not be deleted, regardless of how many exist.

The default value is "1800".

Example command to change or set:

tux > sudo snapper -c CONFIG set-config "NUMBER_MIN_AGE=864000"
Note
Note: Limit and Age

NUMBER_LIMIT, NUMBER_LIMIT_IMPORTANT and NUMBER_MIN_AGE are always evaluated. Snapshots are only deleted when all conditions are met.

If you always want to keep the number of snapshots defined with NUMBER_LIMIT* regardless of their age, set NUMBER_MIN_AGE to 0.

The following example shows a configuration to keep the last 10 important and regular snapshots regardless of age:

NUMBER_CLEANUP=yes
NUMBER_LIMIT_IMPORTANT=10
NUMBER_LIMIT=10
NUMBER_MIN_AGE=0

On the other hand, if you do not want to keep snapshots beyond a certain age, set NUMBER_LIMIT* to 0 and provide the age with NUMBER_MIN_AGE.

The following example shows a configuration to only keep snapshots younger than ten days:

NUMBER_CLEANUP=yes
NUMBER_LIMIT_IMPORTANT=0
NUMBER_LIMIT=0
NUMBER_MIN_AGE=864000

7.6.2 Cleaning Up Timeline Snapshots

Cleaning up timeline snapshots is controlled by the following parameters of a Snapper configuration.

TIMELINE_CLEANUP

Enables or disables clean-up of timeline snapshots. If enabled, snapshots are deleted when the total snapshot count exceeds a number specified with TIMELINE_LIMIT_* and an age specified with TIMELINE_MIN_AGE. Valid values: yes, no.

The default value is "yes".

Example command to change or set:

tux > sudo snapper -c CONFIG set-config "TIMELINE_CLEANUP=yes"
TIMELINE_LIMIT_DAILY, TIMELINE_LIMIT_HOURLY, TIMELINE_LIMIT_MONTHLY, TIMELINE_LIMIT_WEEKLY, TIMELINE_LIMIT_YEARLY

Number of snapshots to keep for hour, day, month, week, and year.

The default value for each entry is "10", except for TIMELINE_LIMIT_WEEKLY, which is set to "0" by default.

TIMELINE_MIN_AGE

Defines the minimum age in seconds a snapshot must have before it can automatically be deleted.

The default value is "1800".

Example 7.1: Example timeline configuration
TIMELINE_CLEANUP="yes"
TIMELINE_CREATE="yes"
TIMELINE_LIMIT_DAILY="7"
TIMELINE_LIMIT_HOURLY="24"
TIMELINE_LIMIT_MONTHLY="12"
TIMELINE_LIMIT_WEEKLY="4"
TIMELINE_LIMIT_YEARLY="2"
TIMELINE_MIN_AGE="1800"

This example configuration enables hourly snapshots which are automatically cleaned up. TIMELINE_MIN_AGE and TIMELINE_LIMIT_* are always both evaluated. In this example, the minimum age of a snapshot before it can be deleted is set to 30 minutes (1800 seconds). Since we create hourly snapshots, this ensures that only the latest snapshots are kept. If TIMELINE_LIMIT_DAILY is set to not zero, this means that the first snapshot of the day is kept, too.

Snapshots to be Kept
  • Hourly: The last 24 snapshots that have been made.

  • Daily: The first daily snapshot that has been made is kept from the last seven days.

  • Monthly: The first snapshot made on the last day of the month is kept for the last twelve months.

  • Weekly: The first snapshot made on the last day of the week is kept from the last four weeks.

  • Yearly: The first snapshot made on the last day of the year is kept for the last two years.

7.6.3 Cleaning Up Snapshot Pairs That Do Not Differ

As explained in Section 7.1.1, “Types of Snapshots”, whenever you run a YaST module or execute Zypper, a pre snapshot is created on start-up and a post snapshot is created when exiting. In case you have not made any changes there will be no difference between the pre and post snapshots. Such empty snapshot pairs can be automatically be deleted by setting the following parameters in a Snapper configuration:

EMPTY_PRE_POST_CLEANUP

If set to yes, pre and post snapshot pairs that do not differ will be deleted.

The default value is "yes".

EMPTY_PRE_POST_MIN_AGE

Defines the minimum age in seconds a pre and post snapshot pair that does not differ must have before it can automatically be deleted.

The default value is "1800".

7.6.4 Cleaning Up Manually Created Snapshots

Snapper does not offer custom clean-up algorithms for manually created snapshots. However, you can assign the number or timeline clean-up algorithm to a manually created snapshot. If you do so, the snapshot will join the clean-up queue for the algorithm you specified. You can specify a clean-up algorithm when creating a snapshot, or by modifying an existing snapshot:

snapper create --description "Test" --cleanup-algorithm number

Creates a stand-alone snapshot (type single) for the default (root) configuration and assigns the number clean-up algorithm.

snapper modify --cleanup-algorithm "timeline" 25

Modifies the snapshot with the number 25 and assigns the clean-up algorithm timeline.

7.6.5 Adding Disk Quota Support

In addition to the number and/or timeline clean-up algorithms described above, Snapper supports quotas. You can define what percentage of the available space snapshots are allowed to occupy. This percentage value always applies to the Btrfs subvolume defined in the respective Snapper configuration.

If Snapper was enabled during the installation, quota support is automatically enabled. In case you manually enable Snapper at a later point in time, you can enable quota support by running snapper setup-quota. This requires a valid configuration (see Section 7.4, “Creating and Modifying Snapper Configurations” for more information).

Quota support is controlled by the following parameters of a Snapper configuration.

QGROUP

The Btrfs quota group used by Snapper. If not set, run snapper setup-quota. If already set, only change if you are familiar with man 8 btrfs-qgroup. This value is set with snapper setup-quota and should not be changed.

SPACE_LIMIT

Limit of space snapshots are allowed to use in fractions of 1 (100%). Valid values range from 0 to 1 (0.1 = 10%, 0.2 = 20%, ...).

The following limitations and guidelines apply:

  • Quotas are only activated in addition to an existing number and/or timeline clean-up algorithm. If no clean-up algorithm is active, quota restrictions are not applied.

  • With quota support enabled, Snapper will perform two clean-up runs if required. The first run will apply the rules specified for number and timeline snapshots. Only if the quota is exceeded after this run, the quota-specific rules will be applied in a second run.

  • Even if quota support is enabled, Snapper will always keep the number of snapshots specified with the NUMBER_LIMIT* and TIMELINE_LIMIT* values, even if the quota will be exceeded. It is therefore recommended to specify ranged values (MIN-MAX) for NUMBER_LIMIT* and TIMELINE_LIMIT* to ensure the quota can be applied.

    If, for example, NUMBER_LIMIT=5-20 is set, Snapper will perform a first clean-up run and reduce the number of regular numbered snapshots to 20. In case these 20 snapshots exceed the quota, Snapper will delete the oldest ones in a second run until the quota is met. A minimum of five snapshots will always be kept, regardless of the amount of space they occupy.

7.7 Frequently Asked Questions

Why does Snapper Never Show Changes in /var/log, /tmp and Other Directories?

For some directories we decided to exclude them from snapshots. See Section 7.1.2, “Directories That Are Excluded from Snapshots” for a list and reasons. To exclude a path from snapshots we create a subvolume for that path.

How much disk space is used by snapshots? How to free disk space?

Displaying the amount of disk space a snapshot allocates is currently not supported by the Btrfs tools. However, if you have quota enabled, it is possible to determine how much space would be freed if all snapshots would be deleted:

  1. Get the quota group ID (1/0 in the following example):

    tux > sudo snapper -c root get-config | grep QGROUP
    QGROUP                 | 1/0
  2. Rescan the subvolume quotas:

    tux > sudo btrfs quota rescan -w /
  3. Show the data of the quota group (1/0 in the following example):

    tux > sudo btrfs qgroup show / | grep "1/0"
    1/0           4.80GiB    108.82MiB

    The third column shows the amount of space that would be freed when deleting all snapshots (108.82MiB).

To free space on a Btrfs partition containing snapshots you need to delete unneeded snapshots rather than files. Older snapshots occupy more space than recent ones. See Section 7.1.3.4, “Controlling Snapshot Archiving” for details.

Doing an upgrade from one service pack to another results in snapshots occupying a lot of disk space on the system subvolumes, because a lot of data gets changed (package updates). Manually deleting these snapshots after they are no longer needed is recommended. See Section 7.5.4, “Deleting Snapshots” for details.

Can I Boot a Snapshot from the Boot Loader?

Yes—refer to Section 7.3, “System Rollback by Booting from Snapshots” for details.

How to make a snapshot permanent?

Currently Snapper does not offer means to prevent a snapshot from being deleted manually. However, you can prevent snapshots from being automatically deleted by clean-up algorithms. Manually created snapshots (see Section 7.5.2, “Creating Snapshots”) have no clean-up algorithm assigned unless you specify one with --cleanup-algorithm. Automatically created snapshots always either have the number or timeline algorithm assigned. To remove such an assignment from one or more snapshots, proceed as follows:

  1. List all available snapshots:

    tux > sudo snapper list -a
  2. Memorize the number of the snapshot(s) you want to prevent from being deleted.

  3. Run the following command and replace the number placeholders with the number(s) you memorized:

    tux > sudo snapper modify --cleanup-algorithm "" #1 #2 #n
  4. Check the result by running snapper list -a again. The entry in the column Cleanup should now be empty for the snapshots you modified.

Where can I get more information on Snapper?

See the Snapper home page at http://snapper.io/.

8 Remote Access with VNC

  • Filename: vnc.xml
  • ID: cha.vnc
Abstract

Virtual Network Computing (VNC) enables you to control a remote computer via a graphical desktop (as opposed to a remote shell access). VNC is platform-independent and lets you access the remote machine from any operating system.

SUSE Linux Enterprise Server supports two different kinds of VNC sessions: One-time sessions that live as long as the VNC connection from the client is kept up, and persistent sessions that live until they are explicitly terminated.

Note
Note: Session Types

A machine can offer both kinds of sessions simultaneously on different ports, but an open session cannot be converted from one type to the other.

8.1 The vncviewer Client

To connect to a VNC service provided by a server, a client is needed. The default in SUSE Linux Enterprise Server is vncviewer, provided by the tigervnc package.

8.1.1 Connecting Using the vncviewer CLI

To start your VNC viewer and initiate a session with the server, use the command:

tux > vncviewer jupiter.example.com:1

Instead of the VNC display number you can also specify the port number with two colons:

tux > vncviewer jupiter.example.com::5901
Note
Note: Display and Port Number

The actual display or port number you specify in the VNC client must be the same as the display or port number picked by the vncserver command on the target machine. See Section 8.4, “Persistent VNC Sessions” for further info.

8.1.2 Connecting Using the vncviewer GUI

By running vncviewer without specifying --listen or a host to connect to, it will show a window to ask for connection details. Enter the host into the VNC server field like in Section 8.1.1, “Connecting Using the vncviewer CLI” and click Connect.

vncviewer asking for connection details
Figure 8.1: vncviewer

8.1.3 Notification of Unencrypted Connections

The VNC protocol supports different kinds of encrypted connections, not to be confused with password authentication. If a connection does not use TLS, the text (Connection not encrypted!) can be seen in the window title of the VNC viewer.

8.2 Remmina: the Remote Desktop Client

Remmina is a modern and feature rich remote desktop client. It supports several access methods, for example VNC, SSH, RDP, or Spice.

8.2.1 Installation

To use Remmina, verify whether the remmina package is installed on your system, and install it if not. Remember to install the VNC plug-in for Remmina as well:

root # zypper in remmina remmina-plugin-vnc

8.2.2 Main Window

Run Remmina by entering the remmina command.

Remmina's Main Window
Figure 8.2: Remmina's Main Window

The main application window shows the list of stored remote sessions. Here you can add and save a new remote session, quick-start a new session without saving it, start a previously saved session, or set Remmina's global preferences.

8.2.3 Adding Remote Sessions

To add and save a new remote session, click Add new session in the top left of the main window. The Remote Desktop Preference window opens.

Remote Desktop Preference
Figure 8.3: Remote Desktop Preference

Complete the fields that specify your newly added remote session profile. The most important are:

Name

Name of the profile. It will be listed in the main window.

Protocol

The protocol to use when connection to the remote session, for example VNC.

Server

The IP or DNS address and display number of the remote server.

User name, Password

Credentials to use for remote authentication. Leave empty for no authentication.

Color depth, Quality

Select the best options according to you connection speed and quality.

Select the Advanced tab to enter more specific settings.

Tip
Tip: Disable Encryption

If the communication between the client and the remote server is not encrypted, activate Disable encryption, otherwise the connection fails.

Select the SSH tab for advanced SSH tunneling and authentication options.

Confirm with Save. Your new profile will be listed in the main window.

8.2.4 Starting Remote Sessions

You can either start a previously saved session, or quick-start a remote session without saving the connection details.

8.2.4.1 Quick-starting Remote Sessions

To start a remote session quickly without proper adding and saving connection details, use the drop-down box and text field at the top of the main window.

Quick-starting
Figure 8.4: Quick-starting

Select the communication protocol from the drop-down box, for example 'VNC', then enter the VNC server DNS or IP address followed by a colon and a display number, and confirm with Enter.

8.2.4.2 Opening Saved Remote Sessions

To open a specific remote session, double-click it from the list of sessions.

8.2.4.3 Remote Sessions Window

Remote sessions are opened in tabs of a separate window. Each tab hosts one session. The toolbar on the left of the window helps you manage the windows / sessions, such as toggle fullscreen mode, resize the window to match the display size of the session, send specific keystrokes to the session, take screenshots of the session, or set the image quality.

Remmina Viewing SLES 15 Remote Session
Figure 8.5: Remmina Viewing SLES 15 Remote Session

8.2.5 Editing, Copying, and Deleting Saved Sessions

To edit a saved remote session, right-click its name in the Remmina's main window and select Edit. Refer to Section 8.2.3, “Adding Remote Sessions” for the description of the relevant fields.

To copy a saved remote session, right-click its name in the Remmina's main window and select Copy. In the Remote Desktop Preference window, change the name of the profile, optionally adjust relevant options, and confirm with Save.

To Delete a saved remote session, right-click its name in the Remmina's main window and select Delete. Confirm with Yes in the next dialog.

8.2.6 Running Remote Sessions from the Command Line

If you need to open a remote session from the command line or from a batch file without first opening the main application window, use the following syntax:

 tux > remmina -c profile_name.remmina

Remmina's profile files are stored in the .local/share/remmina/ directory in your home directory. To determine which profile file belongs to the session you want to open, run Remmina, click the session name in the main window, and read the path to the profile file in the window's status line at the bottom.

Reading Path to the Profile File
Figure 8.6: Reading Path to the Profile File

While Remmina is not running, you can rename the profile file to to a more reasonable file name, such as sle15.remmina. You can even copy the profile file to your custom directory and run it using the remmina -c command from there.

8.3 One-time VNC Sessions

A one-time session is initiated by the remote client. It starts a graphical login screen on the server. This way you can choose the user which starts the session and, if supported by the login manager, the desktop environment. When you terminate the client connection to such a VNC session, all applications started within that session will be terminated, too. One-time VNC sessions cannot be shared, but it is possible to have multiple sessions on a single host at the same time.

Procedure 8.1: Enabling One-time VNC Sessions
  1. Start YaST › Network Services › Remote Administration (VNC).

  2. Check Allow Remote Administration Without Session Management.

  3. Activate Enable access using a web browser if you plan to access the VNC session in a Web browser window.

  4. If necessary, also check Open Port in Firewall (for example, when your network interface is configured to be in the External Zone). If you have more than one network interface, restrict opening the firewall ports to a specific interface via Firewall Details.

  5. Confirm your settings with Next.

  6. In case not all needed packages are available yet, you need to approve the installation of missing packages.

    Tip
    Tip: Restart the Display Manager

    YaST makes changes to the display manager settings. You need to log out of your current graphical session and restart the display manager for the changes to take effect.

Remote Administration
Figure 8.7: Remote Administration

8.3.1 Available Configurations

The default configuration on SUSE Linux Enterprise Server serves sessions with a resolution of 1024x768 pixels at a color depth of 16-bit. The sessions are available on ports 5901 for regular VNC viewers (equivalent to VNC display 1) and on port 5801 for Web browsers.

Other configurations can be made available on different ports, see Section 8.3.3, “Configuring One-time VNC Sessions”.

VNC display numbers and X display numbers are independent in one-time sessions. A VNC display number is manually assigned to every configuration that the server supports (:1 in the example above). Whenever a VNC session is initiated with one of the configurations, it automatically gets a free X display number.

By default, both the VNC client and server try to communicate securely via a self-signed SSL certificate, which is generated after installation. You can either use the default one, or replace it with your own. When using the self-signed certificate, you need to confirm its signature before the first connection.

8.3.2 Initiating a One-time VNC Session

To connect to a one-time VNC session, a VNC viewer must be installed, see also Section 8.1, “The vncviewer Client”.

8.3.3 Configuring One-time VNC Sessions

You can skip this section, if you do not need or want to modify the default configuration.

One-time VNC sessions are started via the systemd socket xvnc.socket. By default it offers six configuration blocks: three for VNC viewers (vnc1 to vnc3), and three serving a Java applet (vnchttpd1 to vnchttpd3). By default only vnc1 and vnchttpd1 are active.

To activate the VNC server socket at boot time, run the following command:

sudo systemctl enable xvnc.socket

To start the socket immediately, run:

sudo systemctl start xvnc.socket

The Xvnc server can be configured via the server_args option. For a list of options, see Xvnc --help.

When adding custom configurations, make sure they are not using ports that are already in use by other configurations, other services, or existing persistent VNC sessions on the same host.

Activate configuration changes by entering the following command:

tux > sudo systemctl reload xvnc.socket
Important
Important: Firewall and VNC Ports

When activating Remote Administration as described in Procedure 8.1, “Enabling One-time VNC Sessions”, the ports 5801 and 5901 are opened in the firewall. If the network interface serving the VNC sessions is protected by a firewall, you need to manually open the respective ports when activating additional ports for VNC sessions. See Chapter 15, Masquerading and Firewalls for instructions.

8.4 Persistent VNC Sessions

A persistent session can be accessed from multiple clients simultaneously. This is ideal for demonstration purposes where one client has full access and all other clients have view-only access. Another use case are trainings where the trainer might need access to the trainee's desktop.

Tip
Tip: Connecting to a Persistent VNC Session

To connect to a persistent VNC session, a VNC viewer must be installed. Refer to Section 8.1, “The vncviewer Client” for more details.

There are two types of persistent VNC sessions:

8.4.1 VNC Session Initiated using vncserver

This type of persistent VNC session is initiated on the server. The session and all applications started in this session run regardless of client connections until the session is terminated. Access to persistent sessions is protected by two possible types of passwords:

  • a regular password that grants full access or

  • an optional view-only password that grants a non-interactive (view-only) access.

A session can have multiple client connections of both kinds at once.

Procedure 8.2: Starting a Persistent VNC Session using vncserver
  1. Open a shell and make sure you are logged in as the user that should own the VNC session.

  2. If the network interface serving the VNC sessions is protected by a firewall, you need to manually open the port used by your session in the firewall. If starting multiple sessions you may alternatively open a range of ports. See Chapter 15, Masquerading and Firewalls for details on how to configure the firewall.

    vncserver uses the ports 5901 for display :1, 5902 for display :2, and so on. For persistent sessions, the VNC display and the X display usually have the same number.

  3. To start a session with a resolution of 1024x769 pixel and with a color depth of 16-bit, enter the following command:

    vncserver -alwaysshared -geometry 1024x768 -depth 16

    The vncserver command picks an unused display number when none is given and prints its choice. See man 1 vncserver for more options.

When running vncserver for the first time, it asks for a password for full access to the session. If needed, you can also provide a password for view-only access to the session.

The password(s) you are providing here are also used for future sessions started by the same user. They can be changed with the vncpasswd command.

Important
Important: Security Considerations

Make sure to use strong passwords of significant length (eight or more characters). Do not share these passwords.

To terminate the session shut down the desktop environment that runs inside the VNC session from the VNC viewer as you would shut it down if it was a regular local X session.

If you prefer to manually terminate a session, open a shell on the VNC server and make sure you are logged in as the user that owns the VNC session you want to terminate. Run the following command to terminate the session that runs on display :1: vncserver -kill :1

8.4.1.1 Configuring Persistent VNC Sessions

Persistent VNC sessions can be configured by editing $HOME/.vnc/xstartup. By default this shell script starts the same GUI/window manager it was started from. In SUSE Linux Enterprise Server this will either be GNOME or IceWM. If you want to start your session with a window manager of your choice, set the variable WINDOWMANAGER:

WINDOWMANAGER=gnome vncserver -geometry 1024x768
WINDOWMANAGER=icewm vncserver -geometry 1024x768
Note
Note: One Configuration for Each User

Persistent VNC sessions are configured in a single per-user configuration. Multiple sessions started by the same user will all use the same start-up and password files.

8.4.2 VNC Session Initiated using vncmanager

Procedure 8.3: Enabling Persistent VNC Sessions
  1. Start YaST › Network Services › Remote Administration (VNC).

  2. Activate Allow Remote Administration With Session Management.

  3. Activate Enable access using a web browser if you plan to access the VNC session in a Web browser window.

  4. If necessary, also check Open Port in Firewall (for example, when your network interface is configured to be in the External Zone). If you have more than one network interface, restrict opening the firewall ports to a specific interface via Firewall Details.

  5. Confirm your settings with Next.

  6. In case not all needed packages are available yet, you need to approve the installation of missing packages.

    Tip
    Tip: Restart the Display Manager

    YaST makes changes to the display manager settings. You need to log out of your current graphical session and restart the display manager for the changes to take effect.

8.4.2.1 Configuring Persistent VNC Sessions

After you enable the VNC session management as described in Procedure 8.3, “Enabling Persistent VNC Sessions”, you can normally connect to the remote session with your favorite VNC viewer, such as vncviewer or Remmina. You will be presented with login screen. After you log in, the 'VNC' icon will appear in the system tray of your desktop environment. Click the icon to open the VNC Session window. If it does not appear or if your desktop environment does not support icons in the system tray, run vncmanager-controller manually.

VNC Session Settings
Figure 8.8: VNC Session Settings

There are several settings which influence the VNC session behavior:

Non-persistent, private

This is equivalent to one-time session. Such session is not visible to others and will be terminated after you disconnect from it. Refer to Section 8.3, “One-time VNC Sessions” for more information.

Persistent, visible

The session is visible to other users and keeps running even after you disconnect from it.

Session name

Here you can specify the name of the persistent session so that it is easily identified when reconnecting.

No password required

The session will be freely accessible without having to log in under user credentials.

Require user login

You need to log in with a valid user name and password to access the session. List the valid user names in the Allowed users text box.

Allow one client at time

Disables joining the session by multiple users at the same time.

Allow multiple clients at time

Allows multiple users to join the persistent session at the same time. Good for example for remote presentations or trainings.

Confirm with OK.

8.4.2.2 Joining Persistent VNC Sessions

After you set up a persistent VNC session as described in Section 8.4.2.1, “Configuring Persistent VNC Sessions”, you can join it with your VNC viewer. After the your VNC client connects to the server, you will be prompted to choose whether you want to create a new session, or join the existing one:

Joining a Persistent VNC Session
Figure 8.9: Joining a Persistent VNC Session

After you click the name of the existing session, you may be asked for login credentials, depending on the persistent session settings.

8.5 Encrypted VNC Communication

If the VNC server is set up properly, all communication between the VNC server and the client is encrypted. The authentication happens at the beginning of the session, the actual data transfer only begins afterward.

Whether for a one-time or a persistent VNC session, security options are configured via the -securitytypes parameter of the /usr/bin/Xvnc command located on the server_args line. The -securitytypes parameter selects both authentication method and encryption. It has the following options:

Authentications
None, TLSNone, X509None

No authentication.

VncAuth, TLSVnc, X509Vnc

Authentication using custom password.

Plain, TLSPlain, X509Plain

Authentication using PAM to verify user's password.

Encryptions
None, VncAuth, Plain

No encryption.

TLSNone, TLSVnc, TLSPlain

Anonymous TLS encryption. Everything is encrypted, but there is no verification of the remote host. So you are protected against passive attackers, but not against man-in-the-middle attackers.

X509None, X509Vnc, X509Plain

TLS encryption with certificate. If you use a self-signed certificate, you will be asked to verify it on the first connection. On subsequent connections you will be warned only if the certificate changed. So you are protected against everything except man-in-the-middle on the first connection (similar to typical SSH usage). If you use a certificate signed by a certificate authority matching the machine name, then you get full security (similar to typical HTTPS usage).

Tip
Tip: Path to Certificate and Key

With X509 based encryption, you need to specify the path to the X509 certificate and the key with -X509Cert and -X509Key options.

If you select multiple security types separated by comma, the first one supported and allowed by both client and server will be used. That way you can configure opportunistic encryption on the server. This is useful if you need to support VNC clients that do not support encryption.

On the client, you can also specify the allowed security types to prevent a downgrade attack if you are connecting to a server which you know has encryption enabled (although our vncviewer will warn you with the "Connection not encrypted!" message in that case).

9 File Copying with RSync

  • Filename: net_sync.xml
  • ID: cha.net.sync
Abstract

Today, a typical user has several computers: home and workplace machines, a laptop, a smartphone or a tablet. This makes the task of keeping files and documents in sync across multiple devices all more important.

Warning
Warning: Risk of Data Loss

Before you start using a synchronization tool, you should familiarize yourself with its features and functionality. Make sure to back up your important files.

9.1 Conceptual Overview

For synchronizing a large amount of data over a slow network connection, Rsync offers a reliable method of transmitting only changes within files. This applies not only to text files but also binary files. To detect the differences between files, Rsync subdivides the files into blocks and computes check sums over them.

Detecting changes requires some computing power. So make sure that machines on both ends have enough resources, including RAM.

Rsync can be particularly useful when large amounts of data containing only minor changes need to be transmitted regularly. This is often the case when working with backups. Rsync can also be useful for mirroring staging servers that store complete directory trees of Web servers to a Web server in a DMZ.

Despite its name, Rsync is not a synchronization tool. Rsync is a tool that copies data only in one direction at a time. It does not and cannot do the reverse. If you need a bidirectional tool which is able to synchronize both source and destination, use Csync.

9.2 Basic Syntax

Rsync is a command-line tool that has the following basic syntax:

rsync [OPTION] SOURCE [SOURCE]... DEST

You can use Rsync on any local or remote machine, provided you have access and write permissions. It is possible to have multiple SOURCE entries. The SOURCE and DEST placeholders can be paths, URLs, or both.

Below are the most common Rsync options:

-v

Outputs more verbose text

-a

Archive mode; copies files recursively and preserves timestamps, user/group ownership, file permissions, and symbolic links

-z

Compresses the transmitted data

Note
Note: Trailing Slashes Count

When working with Rsync, you should pay particular attention to trailing slashes. A trailing slash after the directory denotes the content of the directory. No trailing slash denotes the directory itself.

9.3 Copying Files and Directories Locally

The following description assumes that the current user has write permissions to the directory /var/backup. To copy a single file from one directory on your machine to another path, use the following command:

tux > rsync -avz backup.tar.xz /var/backup/

The file backup.tar.xz is copied to /var/backup/; the absolute path will be /var/backup/backup.tar.xz.

Do not forget to add the trailing slash after the /var/backup/ directory! If you do not insert the slash, the file backup.tar.xz is copied to /var/backup (file) not inside the directory /var/backup/!

Copying a directory is similar to copying a single file. The following example copies the directory tux/ and its content into the directory /var/backup/:

tux > rsync -avz tux /var/backup/

Find the copy in the absolute path /var/backup/tux/.

9.4 Copying Files and Directories Remotely

The Rsync tool is required on both machines. To copy files from or to remote directories requires an IP address or a domain name. A user name is optional if your current user names on the local and remote machine are the same.

To copy the file file.tar.xz from your local host to the remote host 192.168.1.1 with same users (being local and remote), use the following command:

tux > rsync -avz file.tar.xz  tux@192.168.1.1:

Depending on what you prefer, these commands are also possible and equivalent:

tux > rsync -avz file.tar.xz 192.168.1.1:~
tux > rsync -avz file.tar.xz 192.168.1.1:/home/tux

In all cases with standard configuration, you will be prompted to enter your passphrase of the remote user. This command will copy file.tar.xz to the home directory of user tux (usually /home/tux).

Copying a directory remotely is similar to copying a directory locally. The following example copies the directory tux/ and its content into the remote directory /var/backup/ on the 192.168.1.1 host:

tux > rsync -avz tux 192.168.1.1:/var/backup/

Assuming you have write permissions on the host 192.168.1.1, you will find the copy in the absolute path /var/backup/tux.

9.5 Configuring and Using an Rsync Server

Rsync can run as a daemon (rsyncd) listing on default port 873 for incoming connections. This daemon can receive copying targets.

The following description explains how to create an Rsync server on jupiter with a backup target. This target can be used to store your backups. To create an Rsync server, do the following:

Procedure 9.1: Setting Up an Rsync Server
  1. On jupiter, create a directory to store all your backup files. In this example, we use /var/backup:

    root # mkdir /var/backup
  2. Specify ownership. In this case, the directory is owned by user tux in group users:

    root # chown tux.users /var/backup
  3. Configure the rsyncd daemon.

    We will separate the configuration file into a main file and some modules which hold your backup target. This makes it easier to add additional targets later. Global values can be stored in /etc/rsyncd.d/*.inc files, whereas your modules are placed in /etc/rsyncd.d/*.conf files:

    1. Create a directory /etc/rsyncd.d/:

      root # mkdir /etc/rsyncd.d/
    2. In the main configuration file /etc/rsyncd.conf, add the following lines:

      # rsyncd.conf main configuration file
      log file = /var/log/rsync.log
      pid file = /var/lock/rsync.lock
      
      &merge /etc/rsyncd.d 1
      &include /etc/rsyncd.d 2

      1

      Merges global values from /etc/rsyncd.d/*.inc files into the main configuration file.

      2

      Loads any modules (or targets) from /etc/rsyncd.d/*.conf files. These files should not contain any references to global values.

    3. Create your module (your backup target) in the file /etc/rsyncd.d/backup.conf with the following lines:

      # backup.conf: backup module
      [backup] 1
         uid = tux 2
         gid = users 2
         path = /var/backup 3
         auth users = tux  4
         secrets file = /etc/rsyncd.secrets 5
         comment = Our backup target

      1

      The backup target. You can use any name you like. However, it is a good idea to name a target according to its purpose and use the same name in your *.conf file.

      2

      Specifies the user name or group name that is used when the file transfer takes place.

      3

      Defines the path to store your backups (from Step 1).

      4

      Specifies a comma-separated list of allowed users. In its simplest form, it contains the user names that are allowed to connect to this module. In our case, only user tux is allowed.

      5

      Specifies the path of a file that contains lines with user names and plain passwords.

    4. Create the /etc/rsyncd.secrets file with the following content and replace PASSPHRASE:

      # user:passwd
      tux:PASSPHRASE
    5. Make sure the file is only readable by root:

      root # chmod 0600 /etc/rsyncd.secrets
  4. Start and enable the rsyncd daemon with:

    root # systemctl enable rsyncd
    root # systemctl start rsyncd
  5. Test the access to your Rsync server:

    tux > rsync jupiter::

    You should see a response that looks like this:

    backup          Our backup target

    Otherwise, check your configuration file, firewall and network settings.

The above steps create an Rsync server that can now be used to store backups. The example also creates a log file listing all connections. This file is stored in /var/log/rsyncd.log. This is useful if you want to debug your transfers.

To list the content of your backup target, use the following command:

rsync -avz jupiter::backup

This command lists all files present in the directory /var/backup on the server. This request is also logged in the log file /var/log/rsyncd.log. To start an actual transfer, provide a source directory. Use . for the current directory. For example, the following command copies the current directory to your Rsync backup server:

rsync -avz . jupiter::backup

By default, Rsync does not delete files and directories when it runs. To enable deletion, the additional option --delete must be stated. To ensure that no newer files are deleted, the option --update can be used instead. Any conflicts that arise must be resolved manually.

9.6 For More Information

CSync

Bidirectional file synchronizer, see https://www.csync.org/.

RSnapshot

Creates incremental backups, see http://rsnapshot.org.

Unison

A file synchronizer similar to CSync but with a graphical interface, see http://www.seas.upenn.edu/~bcpierce/unison/.

Rear

A disaster recovery framework, see the Administration Guide of the SUSE Linux Enterprise High Availability Extension https://www.suse.com/documentation/sle-ha-12/.

Part II Booting a Linux System

10 Introduction to the Booting Process

Booting a Linux system involves different components and tasks. The hardware itself is initialized by the BIOS or the UEFI, which starts the kernel by means of a boot loader. After this point, the boot process is completely controlled by the operating system and handled by systemd. systemd provides a set of targets that boot setups for everyday usage, maintenance or emergencies.

11 UEFI (Unified Extensible Firmware Interface)

UEFI (Unified Extensible Firmware Interface) is the interface between the firmware that comes with the system hardware, all the hardware components of the system, and the operating system.

12 The Boot Loader GRUB 2

This chapter describes how to configure GRUB 2, the boot loader used in SUSE® Linux Enterprise Server. It is the successor to the traditional GRUB boot loader—now called GRUB Legacy. GRUB 2 has been the default boot loader in SUSE® Linux Enterprise Server since version 12. A YaST module is available for configuring the most important settings. The boot procedure as a whole is outlined in Chapter 10, Introduction to the Booting Process. For details on Secure Boot support for UEFI machines, see Chapter 11, UEFI (Unified Extensible Firmware Interface).

13 The systemd Daemon

The program systemd is the process with process ID 1. It is responsible for initializing the system in the required way. systemd is started directly by the kernel and resists signal 9, which normally terminates processes. All other programs are either started directly by systemd or by one of its chi…

10 Introduction to the Booting Process

  • Filename: bootconcept.xml
  • ID: cha.boot
Abstract

Booting a Linux system involves different components and tasks. The hardware itself is initialized by the BIOS or the UEFI, which starts the kernel by means of a boot loader. After this point, the boot process is completely controlled by the operating system and handled by systemd. systemd provides a set of targets that boot setups for everyday usage, maintenance or emergencies.

10.1 The Linux Boot Process

The Linux boot process consists of several stages, each represented by a different component. The following list briefly summarizes the boot process and features all the major components involved:

  1. BIOS/UEFI.  After turning on the computer, the BIOS or the UEFI initializes the screen and keyboard, and tests the main memory. Up to this stage, the machine does not access any mass storage media. Subsequently, the information about the current date, time, and the most important peripherals are loaded from the CMOS values. When the first hard disk and its geometry are recognized, the system control passes from the BIOS to the boot loader. If the BIOS supports network booting, it is also possible to configure a boot server that provides the boot loader. On AMD64/Intel 64 systems, PXE boot is needed. Other architectures commonly use the BOOTP protocol to get the boot loader. For more information on UEFI, refer to Chapter 11, UEFI (Unified Extensible Firmware Interface).

  2. Boot Loader.  The first physical 512-byte data sector of the first hard disk is loaded into the main memory and the boot loader that resides at the beginning of this sector takes over. The commands executed by the boot loader determine the remaining part of the boot process. Therefore, the first 512 bytes on the first hard disk are called the Master Boot Record (MBR). The boot loader then passes control to the actual operating system, in this case, the Linux kernel. More information about GRUB 2, the Linux boot loader, can be found in Chapter 12, The Boot Loader GRUB 2. For a network boot, the BIOS acts as the boot loader. It gets the boot image from the boot server and starts the system. This is completely independent of local hard disks.

    If the root file system fails to mount from within the boot environment, it must be checked and repaired before the boot can continue. The file system checker will be automatically started for Ext3 and Ext4 file systems. The repair process is not automated for XFS and Btrfs file systems, and the user is be presented with information describing the options available to repair the file system. When the file system has been successfully repaired, exiting the boot environment will cause the system to retry mounting the root file system. If successful, the boot will continue normally.

  3. Kernel and initramfs To pass system control, the boot loader loads both the kernel and an initial RAM-based file system (initramfs) into memory. The contents of the initramfs can be used by the kernel directly. initramfs contains a small executable called init that handles the mounting of the real root file system. If special hardware drivers are needed before the mass storage can be accessed, they must be in initramfs. For more information about initramfs, refer to Section 10.2, “initramfs. If the system does not have a local hard disk, the initramfs must provide the root file system for the kernel. This can be done using a network block device like iSCSI or SAN, but it is also possible to use NFS as the root device.

    Note
    Note: The init Process Naming

    Two different programs are commonly named init:

    1. the initramfs process mounting the root file system

    2. the operating system process setting up the system

    In this chapter we will therefore refer to them as init on initramfs and systemd, respectively.

  4. init on initramfs This program performs all actions needed to mount the proper root file system. It provides kernel functionality for the needed file system and device drivers for mass storage controllers with udev. After the root file system has been found, it is checked for errors and mounted. If this is successful, the initramfs is cleaned and the systemd daemon on the root file system is executed. For more information about init on initramfs, refer to Section 10.3, “Init on initramfs. Find more information about udev in Chapter 21, Dynamic Kernel Device Management with udev.

  5. systemd By starting services and mounting file systems, systemd handles the actual booting of the system. systemd is described in Chapter 13, The systemd Daemon.

10.2 initramfs

initramfs is a small cpio archive that the kernel can load into a RAM disk. It provides a minimal Linux environment that enables the execution of programs before the actual root file system is mounted. This minimal Linux environment is loaded into memory by BIOS or UEFI routines and does not have specific hardware requirements other than sufficient memory. The initramfs archive must always provide an executable named init that executes the systemd daemon on the root file system for the boot process to proceed.

Before the root file system can be mounted and the operating system can be started, the kernel needs the corresponding drivers to access the device on which the root file system is located. These drivers may include special drivers for certain kinds of hard disks or even network drivers to access a network file system. The needed modules for the root file system may be loaded by init on initramfs. After the modules are loaded, udev provides the initramfs with the needed devices. Later in the boot process, after changing the root file system, it is necessary to regenerate the devices. This is done by the systemd unit udev.service with the command udevtrigger.

If you need to change hardware (for example, hard disks), and this hardware requires different drivers to be in the kernel at boot time, you must update the initramfs file. This is done by calling dracut -f (the option -f overwrites the existing initramfs file). To add a driver for the new hardware, edit /etc/dracut.conf.d/01-dist.conf and add the following line. If the file does not exist, create it.

force_drivers+="DRIVER1"

Replace DRIVER1 with the module name of the driver. If you need to add more than one driver, list them space-separated (DRIVER1 DRIVER2).

Important
Important: Updating initramfs or init

The boot loader loads initramfs or init in the same way as the kernel. It is not necessary to re-install GRUB 2 after updating initramfs or init, because GRUB 2 searches the directory for the right file when booting.

Tip
Tip: Changing Kernel Variables

If you change the values of kernel variables via the sysctl interface by editing related files (/etc/sysctl.conf or /etc/sysctl.d/*.conf), the change will be lost on the next system reboot. Even if you load the values with sysctl --system at runtime, the changes are not saved into the initramfs file. You need to update it by calling dracut -f (the option -f overwrites the existing initramfs file).

10.3 Init on initramfs

The main purpose of init on initramfs is to prepare the mounting of and access to the real root file system. Depending on your system configuration, init on initramfs is responsible for the following tasks.

Loading Kernel Modules

Depending on your hardware configuration, special drivers may be needed to access the hardware components of your computer (the most important component being your hard disk). To access the final root file system, the kernel needs to load the proper file system drivers.

Providing Block Special Files

For each loaded module, the kernel generates device events. udev handles these events and generates the required special block files on a RAM file system in /dev. Without those special files, the file system and other devices would not be accessible.

Managing RAID and LVM Setups

If you configured your system to hold the root file system under RAID or LVM, init on initramfs sets up LVM or RAID to enable access to the root file system later.

To change your /usr or swap partitions directly without the help of YaST, further actions are needed. If you forget these steps, your system will start in emergency mode. To avoid starting in emergency mode, perform the following steps:

Procedure 10.1: Updating Init RAM Disk When Switching to Logical Volumes
  1. Edit the corresponding entry in /etc/fstab and replace your previous partitions with the logical volume.

  2. Execute the following commands:

    root # mount -a
    root # swapon -a
  3. Regenerate your initial RAM disk (initramfs) with mkinitrd or dracut.

  4. For z Systems, additionally run grub2-install.

Find more information about RAID and LVM in Chapter 12, Advanced Disk Setup.

Managing Network Configuration

If you configured your system to use a network-mounted root file system (mounted via NFS), init on initramfs must make sure that the proper network drivers are loaded and that they are set up to allow access to the root file system.

If the file system resides on a network block device like iSCSI or SAN, the connection to the storage server is also set up by init on initramfs. SUSE Linux Enterprise Server supports booting from a secondary iSCSI target if the primary target is not available. For more details regarding configuration of the booting iSCSI target refer to Section 14.3.1, “Using YaST for the iSCSI Initiator Configuration”.

When init on initramfs is called during the initial boot as part of the installation process, its tasks differ from those mentioned above:

Finding the Installation Medium

When starting the installation process, your machine loads an installation kernel and a special init containing the YaST installer. The YaST installer is running in a RAM file system and needs to have information about the location of the installation medium to access it for installing the operating system.

Initiating Hardware Recognition and Loading Appropriate Kernel Modules

As mentioned in Section 10.2, “initramfs, the boot process starts with a minimum set of drivers that can be used with most hardware configurations. init starts an initial hardware scanning process that determines the set of drivers suitable for your hardware configuration. These drivers are used to generate a custom initramfs that is needed to boot the system. If the modules are not needed for boot but for coldplug, the modules can be loaded with systemd; for more information, see Section 13.6.4, “Loading Kernel Modules”.

Loading the Installation System

When the hardware is properly recognized, the appropriate drivers are loaded. The udev program creates the special device files and init starts the installation system with the YaST installer.

Starting YaST

Finally, init starts YaST, which starts package installation and system configuration.

11 UEFI (Unified Extensible Firmware Interface)

  • Filename: uefi.xml
  • ID: cha.uefi

UEFI (Unified Extensible Firmware Interface) is the interface between the firmware that comes with the system hardware, all the hardware components of the system, and the operating system.

UEFI is becoming more and more available on PC systems and thus is replacing the traditional PC-BIOS. UEFI, for example, properly supports 64-bit systems and offers secure booting (Secure Boot, firmware version 2.3.1c or better required), which is one of its most important features. Lastly, with UEFI a standard firmware will become available on all x86 platforms.

UEFI additionally offers the following advantages:

  • Booting from large disks (over 2 TiB) with a GUID Partition Table (GPT).

  • CPU-independent architecture and drivers.

  • Flexible pre-OS environment with network capabilities.

  • CSM (Compatibility Support Module) to support booting legacy operating systems via a PC-BIOS-like emulation.

For more information, see http://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface. The following sections are not meant as a general UEFI overview; these are only hints about how some features are implemented in SUSE Linux Enterprise Server.

11.1 Secure Boot

In the world of UEFI, securing the bootstrapping process means establishing a chain of trust. The platform is the root of this chain of trust; in the context of SUSE Linux Enterprise Server, the mainboard and the on-board firmware could be considered the platform. In other words, it is the hardware vendor, and the chain of trust flows from that hardware vendor to the component manufacturers, the OS vendors, etc.

The trust is expressed via public key cryptography. The hardware vendor puts a so-called Platform Key (PK) into the firmware, representing the root of trust. The trust relationship with operating system vendors and others is documented by signing their keys with the Platform Key.

Finally, security is established by requiring that no code will be executed by the firmware unless it has been signed by one of these trusted keys—be it an OS boot loader, some driver located in the flash memory of some PCI Express card or on disk, or be it an update of the firmware itself.

To use Secure Boot, you need to have your OS loader signed with a key trusted by the firmware, and you need the OS loader to verify that the kernel it loads can be trusted.

Key Exchange Keys (KEK) can be added to the UEFI key database. This way, you can use other certificates, as long as they are signed with the private part of the PK.

11.1.1 Implementation on SUSE Linux Enterprise Server

Microsoft’s Key Exchange Key (KEK) is installed by default.

Note
Note: GUID Partitioning Table (GPT) Required

The Secure Boot feature is enabled by default on UEFI/x86_64 installations. You can find the Enable Secure Boot Support option in the Boot Code Options tab of the Boot Loader Settings dialog. It supports booting when the secure boot is activated in the firmware, while making it possible to boot when it is deactivated.

Secure Boot Support
Figure 11.1: Secure Boot Support

The Secure Boot feature requires that a GUID Partitioning Table (GPT) replaces the old partitioning with a Master Boot Record (MBR). If YaST detects EFI mode during the installation, it will try to create a GPT partition. UEFI expects to find the EFI programs on a FAT-formatted EFI System Partition (ESP).

Supporting UEFI Secure Boot essentially requires having a boot loader with a digital signature that the firmware recognizes as a trusted key. That key is trusted by the firmware a priori, without requiring any manual intervention.

There are two ways of getting there. One is to work with hardware vendors to have them endorse a SUSE key, which SUSE then signs the boot loader with. The other way is to go through Microsoft’s Windows Logo Certification program to have the boot loader certified and have Microsoft recognize the SUSE signing key (that is, have it signed with their KEK). By now, SUSE got the loader signed by UEFI Signing Service (that is Microsoft in this case).

UEFI: Secure Boot Process
Figure 11.2: UEFI: Secure Boot Process

At the implementation layer, SUSE uses the shim loader which is installed by default. It is a smart solution that avoids legal issues, and simplifies the certification and signing step considerably. The shim loader’s job is to load a boot loader such as GRUB 2 and verify it; this boot loader in turn will load kernels signed by a SUSE key only. SUSE provides this functionality since SLE11 SP3 on fresh installations with UEFI Secure Boot enabled.

There are two types of trusted users:

  • First, those who hold the keys. The Platform Key (PK) allows almost everything. The Key Exchange Key (KEK) allows all a PK can except changing the PK.

  • Second, anyone with physical access to the machine. A user with physical access can reboot the machine, and configure UEFI.

UEFI offers two types of variables to fulfill the needs of those users:

  • The first is the so-called Authenticated Variables, which can be updated from both within the boot process (the so-called Boot Services Environment) and the running OS. This can be done only when the new value of the variable is signed with the same key that the old value of the variable was signed with. And they can only be appended to or changed to a value with a higher serial number.

  • The second is the so-called Boot Services Only Variables. These variables are accessible to any code that runs during the boot process. After the boot process ends and before the OS starts, the boot loader must call the ExitBootServices call. After that, these variables are no longer accessible, and the OS cannot touch them.

The various UEFI key lists are of the first type, as this allows online updating, adding, and blacklisting of keys, drivers, and firmware fingerprints. It is the second type of variable, the Boot Services Only Variable, that helps to implement Secure Boot in a secure and open source-friendly manner, and thus compatible with GPLv3.

SUSE starts with shim—a small and simple EFI boot loader signed by SUSE and Microsoft.

This allows shim to load and execute.

shim then goes on to verify that the boot loader it wants to load is trusted. In a default situation shim will use an independent SUSE certificate embedded in its body. In addition, shim will allow to enroll additional keys, overriding the default SUSE key. In the following, we call them Machine Owner Keys or MOKs for short.

Next the boot loader will verify and then boot the kernel, and the kernel will do the same on the modules.

11.1.2 MOK (Machine Owner Key)

If the user (machine owner) wants to replace any components of the boot process, Machine Owner Keys (MOKs) are to be used. The mokutils tool will help with signing components and managing MOKs.

The enrollment process begins with rebooting the machine and interrupting the boot process (for example, pressing a key) when shim loads. shim will then go into enrollment mode, allowing the user to replace the default SUSE key with keys from a file on the boot partition. If the user chooses to do so, shim will then calculate a hash of that file and put the result in a Boot Services Only variable. This allows shim to detect any change of the file made outside of Boot Services and thus avoid tampering with the list of user-approved MOKs.

All of this happens during boot time—only verified code is executing now. Therefore, only a user present at the console can use the machine owner's set of keys. It cannot be malware or a hacker with remote access to the OS because hackers or malware can only change the file, but not the hash stored in the Boot Services Only variable.

The boot loader, after having been loaded and verified by shim, will call back to shim when it wants to verify the kernel—to avoid duplication of the verification code. Shim will use the same list of MOKs for this and tell the boot loader whether it can load the kernel.

This way, you can install your own kernel or boot loader. It is only necessary to install a new set of keys and authorize them by being physically present during the first reboot. Because MOKs are a list and not not a single MOK, you can make shim trust keys from several vendors, allowing dual- and multi-boot from the boot loader.

11.1.3 Booting a Custom Kernel

The following is based on http://en.opensuse.org/openSUSE:UEFI#Booting_a_custom_kernel.

Secure Boot does not prevent you from using a self-compiled kernel. You must sign it with your own certificate and make that certificate known to the firmware or MOK.

  1. Create a custom X.509 key and certificate used for signing:

    openssl req -new -x509 -newkey rsa:2048 -keyout key.asc \
      -out cert.pem -nodes -days 666 -subj "/CN=$USER/"

    For more information about creating certificates, see http://en.opensuse.org/openSUSE:UEFI_Image_File_Sign_Tools#Create_Your_Own_Certificate.

  2. Package the key and the certificate as a PKCS#12 structure:

    openssl pkcs12 -export -inkey key.asc -in cert.pem \
      -name kernel_cert -out cert.p12
  3. Generate an NSS database for use with pesign:

    certutil -d . -N
  4. Import the key and the certificate contained in PKCS#12 into the NSS database:

    pk12util -d . -i cert.p12
  5. Bless the kernel with the new signature using pesign:

    pesign -n . -c kernel_cert -i arch/x86/boot/bzImage \
      -o vmlinuz.signed -s
  6. List the signatures on the kernel image:

    pesign -n . -S -i vmlinuz.signed

    At that point, you can install the kernel in /boot as usual. Because the kernel now has a custom signature the certificate used for signing needs to be imported into the UEFI firmware or MOK.

  7. Convert the certificate to the DER format for import into the firmware or MOK:

    openssl x509 -in cert.pem -outform der -out cert.der
  8. Copy the certificate to the ESP for easier access:

    sudo cp cert.der /boot/efi/
  9. Use mokutil to launch the MOK list automatically.

      1. Import the certificate to MOK:

        mokutil --root-pw --import cert.der

        The --root-pw option enables usage of the root user directly.

      2. Check the list of certificates that are prepared to be enrolled:

        mokutil --list-new
      3. Reboot the system; shim should launch MokManager. You need to enter the root password to confirm the import of the certificate to the MOK list.

      4. Check if the newly imported key was enrolled:

        mokutil --list-enrolled
      1. Alternatively, this is the procedure if you want to launch MOK manually:

        Reboot

      2. In the GRUB 2 menu press the 'c' key.

      3. Type:

        chainloader $efibootdir/MokManager.efi
        boot
      4. Select Enroll key from disk.

      5. Navigate to the cert.der file and press Enter.

      6. Follow the instructions to enroll the key. Normally this should be pressing '0' and then 'y' to confirm.

        Alternatively, the firmware menu may provide ways to add a new key to the Signature Database.

11.1.4 Using Non-Inbox Drivers

There is no support for adding non-inbox drivers (that is, drivers that do not come with SUSE Linux Enterprise Server) during installation with Secure Boot enabled. The signing key used for SolidDriver/PLDP is not trusted by default.

It is possible to install third party drivers during installation with Secure Boot enabled in two different ways. In both cases:

  • Add the needed keys to the firmware database via firmware/system management tools before the installation. This option depends on the specific hardware you are using. Consult your hardware vendor for more information.

  • Use a bootable driver ISO from https://drivers.suse.com/ or your hardware vendor to enroll the needed keys in the MOK list at first boot.

To use the bootable driver ISO to enroll the driver keys to the MOK list, follow these steps:

  1. Burn the ISO image above to an empty CD/DVD medium.

  2. Start the installation using the new CD/DVD medium, having the standard installation media at hand or a URL to a network installation server.

    If doing a network installation, enter the URL of the network installation source on the boot command line using the install= option.

    If doing installation from optical media, the installer will first boot from the driver kit and then ask to insert the first installation disk of the product.

  3. An initrd containing updated drivers will be used for installation.

For more information, see https://drivers.suse.com/doc/Usage/Secure_Boot_Certificate.html.

11.1.5 Features and Limitations

When booting in Secure Boot mode, the following features apply:

  • Installation to UEFI default boot loader location, a mechanism to keep or restore the EFI boot entry.

  • Reboot via UEFI.

  • Xen hypervisor will boot with UEFI when there is no legacy BIOS to fall back to.

  • UEFI IPv6 PXE boot support.

  • UEFI videomode support, the kernel can retrieve video mode from UEFI to configure KMS mode with the same parameters.

  • UEFI booting from USB devices is supported.

When booting in Secure Boot mode, the following limitations apply:

  • To ensure that Secure Boot cannot be easily circumvented, some kernel features are disabled when running under Secure Boot.

  • Boot loader, kernel, and kernel modules must be signed.

  • Kexec and Kdump are disabled.

  • Hibernation (suspend on disk) is disabled.

  • Access to /dev/kmem and /dev/mem is not possible, not even as root user.

  • Access to the I/O port is not possible, not even as root user. All X11 graphical drivers must use a kernel driver.

  • PCI BAR access through sysfs is not possible.

  • custom_method in ACPI is not available.

  • debugfs for asus-wmi module is not available.

  • the acpi_rsdp parameter does not have any effect on the kernel.

11.2 For More Information

12 The Boot Loader GRUB 2

  • Filename: grub2.xml
  • ID: cha.grub2
Abstract

This chapter describes how to configure GRUB 2, the boot loader used in SUSE® Linux Enterprise Server. It is the successor to the traditional GRUB boot loader—now called GRUB Legacy. GRUB 2 has been the default boot loader in SUSE® Linux Enterprise Server since version 12. A YaST module is available for configuring the most important settings. The boot procedure as a whole is outlined in Chapter 10, Introduction to the Booting Process. For details on Secure Boot support for UEFI machines, see Chapter 11, UEFI (Unified Extensible Firmware Interface).

12.1 Main Differences between GRUB Legacy and GRUB 2

  • The configuration is stored in different files.

  • More file systems are supported (for example, Btrfs).

  • Can directly read files stored on LVM or RAID devices.

  • The user interface can be translated and altered with themes.

  • Includes a mechanism for loading modules to support additional features, such as file systems, etc.

  • Automatically searches for and generates boot entries for other kernels and operating systems, such as Windows.

  • Includes a minimal Bash-like console.

12.2 Configuration File Structure

The configuration of GRUB 2 is based on the following files:

/boot/grub2/grub.cfg

This file contains the configuration of the GRUB 2 menu items. It replaces menu.lst used in GRUB Legacy. grub.cfg is automatically generated by the grub2-mkconfig command, and should not be edited.

/boot/grub2/custom.cfg

This optional file is directly sourced by grub.cfg at boot time and can be used to add custom items to the boot menu. Starting with SUSE Linux Enterprise Server these entries will also be parsed when using grub-once.

/etc/default/grub

This file controls the user settings of GRUB 2 and usually includes additional environmental settings such as backgrounds and themes.

Scripts under /etc/grub.d/

The scripts in this directory are read during execution of the grub2-mkconfig command. Their instructions are integrated into the main configuration file /boot/grub/grub.cfg.

/etc/sysconfig/bootloader

This configuration file is used when configuring the boot loader with YaST and every time a new kernel is installed. It is evaluated by the perl-bootloader which modifies the boot loader configuration file (for example /boot/grub2/grub.cfg for GRUB 2) accordingly. /etc/sysconfig/bootloader is not a GRUB 2-specific configuration file—the values are applied to any boot loader installed on SUSE Linux Enterprise Server.

/boot/grub2/x86_64-efi, /boot/grub2/power-ieee1275, /boot/grub2/s390x

These configuration files contain architecture-specific options.

GRUB 2 can be controlled in various ways. Boot entries from an existing configuration can be selected from the graphical menu (splash screen). The configuration is loaded from the file /boot/grub2/grub.cfg which is compiled from other configuration files (see below). All GRUB 2 configuration files are considered system files, and you need root privileges to edit them.

Note
Note: Activating Configuration Changes

After having manually edited GRUB 2 configuration files, you need to run grub2-mkconfig to activate the changes. However, this is not necessary when changing the configuration with YaST, since it will automatically run grub2-mkconfig .

12.2.1 The File /boot/grub2/grub.cfg

The graphical splash screen with the boot menu is based on the GRUB 2 configuration file /boot/grub2/grub.cfg, which contains information about all partitions or operating systems that can be booted by the menu.

Every time the system is booted, GRUB 2 loads the menu file directly from the file system. For this reason, GRUB 2 does not need to be re-installed after changes to the configuration file. grub.cfg is automatically rebuilt with kernel installations or removals.

grub.cfg is compiled by the grub2-mkconfig from the file /etc/default/grub and scripts found in the /etc/grub.d/ directory. Therefore you should never edit the file manually. Instead, edit the related source files or use the YaST Boot Loader module to modify the configuration as described in Section 12.3, “Configuring the Boot Loader with YaST”.

12.2.2 The File /etc/default/grub

More general options of GRUB 2 belong here, such as the time the menu is displayed, or the default OS to boot. To list all available options, see the output of the following command:

grep "export GRUB_DEFAULT" -A50 /usr/sbin/grub2-mkconfig | grep GRUB_

In addition to already defined variables, the user may introduce their own variables, and use them later in the scripts found in the /etc/grub.d directory.

After having edited /etc/default/grub, run grub2-mkconfig to update the main configuration file.

Note
Note: Scope

All options set in this file are general options that affect all boot entries. Specific options for Xen kernels or the Xen hypervisor can be set via the GRUB_*_XEN_* configuration options. See below for details.

GRUB_DEFAULT

Sets the boot menu entry that is booted by default. Its value can be a numeric value, the complete name of a menu entry, or saved.

GRUB_DEFAULT=2 boots the third (counted from zero) boot menu entry.

GRUB_DEFAULT="2>0" boots the first submenu entry of the third top-level menu entry.

GRUB_DEFAULT="Example boot menu entry" boots the menu entry with the title Example boot menu entry.

GRUB_DEFAULT=saved boots the entry specified by the grub2-once or grub2-set-default commands. While grub2-reboot sets the default boot entry for the next reboot only, grub2-set-default sets the default boot entry until changed. grub2-editenv list lists next boot entry.

GRUB_HIDDEN_TIMEOUT

Waits the specified number of seconds for the user to press a key. During the period no menu is shown unless the user presses a key. If no key is pressed during the time specified, the control is passed to GRUB_TIMEOUT. GRUB_HIDDEN_TIMEOUT=0 first checks whether Shift is pressed and shows the boot menu if yes, otherwise immediately boots the default menu entry. This is the default when only one bootable OS is identified by GRUB 2.

GRUB_HIDDEN_TIMEOUT_QUIET

If false is specified, a countdown timer is displayed on a blank screen when the GRUB_HIDDEN_TIMEOUT feature is active.

GRUB_TIMEOUT

Time period in seconds the boot menu is displayed before automatically booting the default boot entry. If you press a key, the timeout is cancelled and GRUB 2 waits for you to make the selection manually. GRUB_TIMEOUT=-1 will cause the menu to be displayed until you select the boot entry manually.

GRUB_CMDLINE_LINUX

Entries on this line are added at the end of the boot entries for normal and recovery mode. Use it to add kernel parameters to the boot entry.

GRUB_CMDLINE_LINUX_DEFAULT

Same as GRUB_CMDLINE_LINUX but the entries are appended in the normal mode only.

GRUB_CMDLINE_LINUX_RECOVERY

Same as GRUB_CMDLINE_LINUX but the entries are appended in the recovery mode only.

GRUB_CMDLINE_LINUX_XEN_REPLACE

This entry will completely replace the GRUB_CMDLINE_LINUX parameters for all Xen boot entries.

GRUB_CMDLINE_LINUX_XEN_REPLACE_DEFAULT

Same as GRUB_CMDLINE_LINUX_XEN_REPLACE but it will only replace parameters ofGRUB_CMDLINE_LINUX_DEFAULT.

GRUB_CMDLINE_XEN

This entry specifies the kernel parameters for the Xen guest kernel only—the operation principle is the same as for GRUB_CMDLINE_LINUX.

GRUB_CMDLINE_XEN_DEFAULT

Same as GRUB_CMDLINE_XEN—the operation principle is the same as for GRUB_CMDLINE_LINUX_DEFAULT.

GRUB_TERMINAL

Enables and specifies an input/output terminal device. Can be console (PC BIOS and EFI consoles), serial (serial terminal), ofconsole (Open Firmware console), or the default gfxterm (graphics-mode output). It is also possible to enable more than one device by quoting the required options, for example GRUB_TERMINAL="console serial".

GRUB_GFXMODE

The resolution used for the gfxterm graphical terminal. Note that you can only use modes supported by your graphics card (VBE). The default is ‘auto’, which tries to select a preferred resolution. You can display the screen resolutions available to GRUB 2 by typing videoinfo in the GRUB 2 command line. The command line is accessed by typing C when the GRUB 2 boot menu screen is displayed.

You can also specify a color depth by appending it to the resolution setting, for example GRUB_GFXMODE=1280x1024x24.

GRUB_BACKGROUND

Set a background image for the gfxterm graphical terminal. The image must be a file readable by GRUB 2 at boot time, and it must end with the .png, .tga, .jpg, or .jpeg suffix. If necessary, the image will be scaled to fit the screen.

GRUB_DISABLE_OS_PROBER

If this option is set to true, automatic searching for other operating systems is disabled. Only the kernel images in /boot/ and the options from your own scripts in /etc/grub.d/ are detected.

SUSE_BTRFS_SNAPSHOT_BOOTING

If this option is set to true, GRUB 2 can boot directly into Snapper snapshots. For more information, see Section 7.3, “System Rollback by Booting from Snapshots”.

For a complete list of options, see the GNU GRUB manual. For a complete list of possible parameters, see http://en.opensuse.org/Linuxrc.

12.2.3 Scripts in /etc/grub.d

The scripts in this directory are read during execution of the grub2-mkconfig command, and their instructions are incorporated into /boot/grub2/grub.cfg. The order of menu items in grub.cfg is determined by the order in which the files in this directory are run. Files with a leading numeral are executed first, beginning with the lowest number. 00_header is run before 10_linux, which would run before 40_custom. If files with alphabetic names are present, they are executed after the numerically-named files. Only executable files generate output to grub.cfg during execution of grub2-mkconfig. By default all files in the /etc/grub.d directory are executable.

Tip
Tip: Persistent Custom Content in grub.cfg

Because /boot/grub2/grub.cfg is recompiled each time grub2-mkconfig is run, any custom content is lost. If you want to insert your lines directly into /boot/grub2/grub.cfg without losing them after grub2-mkconfig is run, insert it between

### BEGIN /etc/grub.d/90_persistent ###

and

### END /etc/grub.d/90_persistent ###

lines. The 90_persistent script ensures that such content will be preserved.

A list of the most important scripts follows:

00_header

Sets environmental variables such as system file locations, display settings, themes, and previously saved entries. It also imports preferences stored in the /etc/default/grub. Normally you do not need to make changes to this file.

10_linux

Identifies Linux kernels on the root device and creates relevant menu entries. This includes the associated recovery mode option if enabled. Only the latest kernel is displayed on the main menu page, with additional kernels included in a submenu.

30_os-prober

This script uses OS-prober to search for Linux and other operating systems and places the results in the GRUB 2 menu. There are sections to identify specific other operating systems, such as Windows or macOS.

40_custom

This file provides a simple way to include custom boot entries into grub.cfg. Make sure that you do not change the exec tail -n +3 $0 part at the beginning.

The processing sequence is set by the preceding numbers with the lowest number being executed first. If scripts are preceded by the same number the alphabetical order of the complete name decides the order.

Tip
Tip: /boot/grub2/custom.cfg

If you create /boot/grub2/custom.cfg and fill it with a custom content, it will be automatically included into /boot/grub2/grub.cfg at boot time.

12.2.4 Mapping between BIOS Drives and Linux Devices

In GRUB Legacy, the device.map configuration file was used to derive Linux device names from BIOS drive numbers. The mapping between BIOS drives and Linux devices cannot always be guessed correctly. For example, GRUB Legacy would get a wrong order if the boot sequence of IDE and SCSI drives is exchanged in the BIOS configuration.

GRUB 2 avoids this problem by using device ID strings (UUIDs) or file system labels when generating grub.cfg. GRUB 2 utilities create a temporary device map on the fly, which is usually sufficient, particularly in the case of single-disk systems.

However, if you need to override the GRUB 2's automatic device mapping mechanism, create your custom mapping file /boot/grub2/device.map. The following example changes the mapping to make DISK 3 the boot disk. Note that GRUB 2 partition numbers start with 1 and not with 0 as in GRUB Legacy.

(hd1)  /dev/disk-by-id/DISK3 ID
(hd2)  /dev/disk-by-id/DISK1 ID
(hd3)  /dev/disk-by-id/DISK2 ID

12.2.5 Editing Menu Entries during the Boot Procedure

Being able to directly edit menu entries is useful when the system does not boot anymore because of a faulty configuration. It can also be used to test new settings without altering the system configuration.

  1. In the graphical boot menu, select the entry you want to edit with the arrow keys.

  2. Press E to open the text-based editor.

  3. Use the arrow keys to move to the line you want to edit.

    GRUB 2 Boot Editor
    Figure 12.1: GRUB 2 Boot Editor

    Now you have two options:

    1. Add space-separated parameters to the end of the line starting with linux or linuxefi to edit the kernel parameters. A complete list of parameters is available at http://en.opensuse.org/Linuxrc.

    2. Or edit the general options to change for example the kernel version. The →| key suggests all possible completions.

  4. Press F10 to boot the system with the changes you made or press Esc to discard your edits and return to the GRUB 2 menu.

Changes made this way only apply to the current boot process and are not saved permanently.

Important
Important: Keyboard Layout During the Boot Procedure

The US keyboard layout is the only one available when booting. See Figure 40.2, “US Keyboard Layout”.

Note
Note: Boot Loader on the Installation Media

The Boot Loader of the installation media on systems with a traditional BIOS is still GRUB Legacy. To add boot options, select an entry and start typing. Additions you make to the installation boot entry will be permanently saved in the installed system.

Note
Note: Editing GRUB 2 Menu Entries on z Systems

Cursor movement and editing commands on IBM z Systems differ—see Section 12.4, “Differences in Terminal Usage on z Systems” for details.

12.2.6 Setting a Boot Password

Even before the operating system is booted, GRUB 2 enables access to file systems. Users without root permissions can access files in your Linux system to which they have no access after the system is booted. To block this kind of access or to prevent users from booting certain menu entries, set a boot password.

Important
Important: Booting Requires Password

If set, the boot password is required on every boot, which means the system does not boot automatically.

Proceed as follows to set a boot password. Alternatively use YaST (Protect Boot Loader with Password ).

  1. Encrypt the password using grub2-mkpasswd-pbkdf2:

    tux >  sudo grub2-mkpasswd-pbkdf2
    Password: ****
    Reenter password: ****
    PBKDF2 hash of your password is grub.pbkdf2.sha512.10000.9CA4611006FE96BC77A...
  2. Paste the resulting string into the file /etc/grub.d/40_custom together with the set superusers command.

    set superusers="root"
    password_pbkdf2 root grub.pbkdf2.sha512.10000.9CA4611006FE96BC77A...
  3. Run grub2-mkconfig to import the changes into the main configuration file.

After you reboot, you will be prompted for a user name and a password when trying to boot a menu entry. Enter root and the password you typed during the grub2-mkpasswd-pbkdf2 command. If the credentials are correct, the system will boot the selected boot entry.

For more information, see https://www.gnu.org/software/grub/manual/grub.html#Security.

12.3 Configuring the Boot Loader with YaST

  • Filename: grub2_yast_i.xml
  • ID: sec.grub2.yast2.config

The easiest way to configure general options of the boot loader in your SUSE Linux Enterprise Server system is to use the YaST module. In the YaST Control Center, select System › Boot Loader. The module shows the current boot loader configuration of your system and allows you to make changes.

Use the Boot Code Options tab to view and change settings related to type, location and advanced loader settings. You can choose whether to use GRUB 2 in standard or EFI mode.

Boot Code Options
Figure 12.2: Boot Code Options
Important
Important: EFI Systems require GRUB2-EFI

If you have an EFI system you can only install GRUB2-EFI, otherwise your system is no longer bootable.

Important
Important: Reinstalling the Boot Loader

To reinstall the boot loader, make sure to change a setting in YaST and then change it back. For example, to reinstall GRUB2-EFI, select GRUB2 first and then immediately switch back to GRUB2-EFI.

Otherwise, the boot loader may only be partially reinstalled.

Note
Note: Custom Boot Loader

To use a boot loader other than the ones listed, select Do Not Install Any Boot Loader. Read the documentation of your boot loader carefully before choosing this option.

12.3.1 Boot Loader Location and Boot Code Options

The default location of the boot loader depends on the partition setup and is either the Master Boot Record (MBR) or the boot sector of the / partition. To modify the location of the boot loader, follow these steps:

Procedure 12.1: Changing the Boot Loader Location
  1. Select the Boot Code Options tab and then choose one of the following options for Boot Loader Location:

    Boot from Master Boot Record

    This installs the boot loader in the MBR of the disk containing the directory /boot. Usually this will be the disk mounted to /, but if /boot is mounted to a separate partition on a different disk, the MBR of that disk will be used.

    Boot from Root Partition

    This installs the boot loader in the boot sector of the / partition.

    Custom Boot Partition

    Use this option to specify the location of the boot loader manually.

  2. Click OK to apply your changes.

Code Options
Figure 12.3: Code Options

The Boot Code Options tab includes the following additional options:

Set Active Flag in Partition Table for Boot Partition

Activates the partition that contains the /boot directorythe PReP partition. Use this option on systems with old BIOS and/or legacy operating systems because they may fail to boot from a non-active partition. It is safe to leave this option active.

Write Generic Boot Code to MBR

If MBR contains a custom 'non-GRUB' code, this option replaces it with a generic, operating system independent code. If you deactivate this option, the system may become unbootable.

Enable Trusted Boot Support

Starts TrustedGRUB2 which supports trusted computing functionality (Trusted Platform Module (TPM)). For more information refer to https://github.com/Sirrix-AG/TrustedGRUB2.

12.3.2 Adjusting the Disk Order

If your computer has more than one hard disk, you can specify the boot sequence of the disks. The first disk in the list is where GRUB 2 will be installed in the case of booting from MBR. It is the disk where SUSE Linux Enterprise Server is installed by default. The rest of the list is a hint for GRUB 2's device mapper (see Section 12.2.4, “Mapping between BIOS Drives and Linux Devices”).

Warning
Warning: Unbootable System

The default value is usually valid for almost all deployments. If you change the boot order of disks wrongly, the system may become unbootable on the next reboot. For example, if the first disk in the list is not part of BIOS boot order, and the other disk in the list have empty MBRs.

Procedure 12.2: Setting the Disk Order
  1. Open the Boot Code Options tab.

  2. Click Edit Disk Boot Order.

  3. If more than one disk is listed, select a disk and click Up or Down to reorder the displayed disks.

  4. Click OK two times to save the changes.

12.3.3 Configuring Advanced Options

Advanced boot options can be configured via the Boot Loader Options tab.

12.3.3.1 Boot Loader Options Tab

Boot loader Options
Figure 12.4: Boot loader Options
Boot Loader Time-Out

Change the value of Time-Out in Seconds by typing in a new value and clicking the appropriate arrow key with your mouse.

Probe Foreign OS

When selected, the boot loader searches for other systems like Windows or other Linux installations.

Hide Menu on Boot

Hides the boot menu and boots the default entry.

Adjusting the Default Boot Entry

Select the desired entry from the Default Boot Section list. Note that the > sign in the boot entry name delimits the boot section and its subsection.

Protect Boot Loader with Password

Protects the boot loader and the system with an additional password. For more information, see Section 12.2.6, “Setting a Boot Password”.

12.3.3.2 Kernel Parameters Tab

Kernel Parameters
Figure 12.5: Kernel Parameters
Console resolution

The Console resolution option specifies the default screen resolution during the boot process.

Kernel Command Line Parameter

The optional kernel parameters are added at the end of the default parameters. For a list of all possible parameters, see http://en.opensuse.org/Linuxrc.

Use graphical console

When checked, the boot menu appears on a graphical splash screen rather than in a text mode. The resolution of the boot screen can be then set from the Console resolution list, and graphical theme definition file can be specified with the Console theme file-chooser.

Use Serial Console

If your machine is controlled via a serial console, activate this option and specify which COM port to use at which speed. See info grub or http://www.gnu.org/software/grub/manual/grub.html#Serial-terminal

12.4 Differences in Terminal Usage on z Systems

On 3215 and 3270 terminals there are some differences and limitations on how to move the cursor and how to issue editing commands within GRUB 2.

12.4.1 Limitations

Interactivity

Interactivity is strongly limited. Typing often does not result in visual feedback. To see where the cursor is, type an underscore (_).

Note
Note: 3270 Compared to 3215

The 3270 terminal is much better at displaying and refreshing screens than the 3215 terminal.

Cursor Movement

Traditional cursor movement is not possible. Alt, Meta, Ctrl and the cursor keys do not work. To move the cursor, use the key combinations listed in Section 12.4.2, “Key Combinations”.

Caret

The caret (^) is used as a control character. To type a literal ^ followed by a letter, type ^, ^, LETTER.

Enter

The Enter key does not work, use ^J instead.

12.4.2 Key Combinations

Common Substitutes:

^J

engage (Enter)

^L

abort, return to previous state

^I

tab completion (in edit and shell mode)

Keys Available in Menu Mode:

^A

first entry

^E

last entry

^P

previous entry

^N

next entry

^G

previous page

^C

next page

^F

boot selected entry or enter submenu (same as ^J)

E

edit selected entry

C

enter GRUB-Shell

Keys Available in Edit Mode:

^P

previous line

^N

next line

^B

backward char

^F

forward char

^A

beginning of line

^E

end of line

^H

backspace

^D

delete

^K

kill line

^Y

yank

^O

open line

^L

refresh screen

^X

boot entry

^C

enter GRUB-Shell

Keys Available in Command Line Mode:

^P

previous command

^N

next command from history

^A

beginning of line

^E

end of line

^B

backward char

^F

forward char

^H

backspace

^D

delete

^K

kill line

^U

discard line

^Y

yank

12.5 Helpful GRUB 2 Commands

grub2-mkconfig

Generates a new /boot/grub2/grub.cfg based on /etc/default/grub and the scripts from /etc/grub.d/.

Example 12.1: Usage of grub2-mkconfig
grub2-mkconfig -o /boot/grub2/grub.cfg
Tip
Tip: Syntax Check

Running grub2-mkconfig without any parameters prints the configuration to STDOUT where it can be reviewed. Use grub2-script-check after /boot/grub2/grub.cfg has been written to check its syntax.

Important
Important: grub2-mkconfig Cannot Repair UEFI Secure Boot Tables

If you are using UEFI Secure Boot and your system is not reaching GRUB 2 correctly anymore, you may need to additionally reinstall Shim and regenerate the UEFI boot table. To do so, use:

root # shim-install --config-file=/boot/grub2/grub.cfg
grub2-mkrescue

Creates a bootable rescue image of your installed GRUB 2 configuration.

Example 12.2: Usage of grub2-mkrescue
grub2-mkrescue -o save_path/name.iso iso
grub2-script-check

Checks the given file for syntax errors.

Example 12.3: Usage of grub2-script-check
grub2-script-check /boot/grub2/grub.cfg
grub2-once

Set the default boot entry for the next boot only. To get the list of available boot entries use the --list option.

Example 12.4: Usage of grub2-once
grub2-once number_of_the_boot_entry
Tip
Tip: grub2-once Help

Call the program without any option to get a full list of all possible options.

12.6 More Information

Extensive information about GRUB 2 is available at http://www.gnu.org/software/grub/. Also refer to the grub info page. You can also search for the keyword GRUB 2 in the Technical Information Search at http://www.suse.com/support to get information about special issues.

13 The systemd Daemon

  • Filename: systemd.xml
  • ID: cha.systemd

The program systemd is the process with process ID 1. It is responsible for initializing the system in the required way. systemd is started directly by the kernel and resists signal 9, which normally terminates processes. All other programs are either started directly by systemd or by one of its child processes.

Starting with SUSE Linux Enterprise Server 12 systemd is a replacement for the popular System V init daemon. systemd is fully compatible with System V init (by supporting init scripts). One of the main advantages of systemd is that it considerably speeds up boot time by aggressively paralleling service starts. Furthermore, systemd only starts a service when it is really needed. Daemons are not started unconditionally at boot time, but rather when being required for the first time. systemd also supports Kernel Control Groups (cgroups), snapshotting and restoring the system state and more. See http://www.freedesktop.org/wiki/Software/systemd/ for details.

13.1 The systemd Concept

This section will go into detail about the concept behind systemd.

13.1.1 What Is systemd

systemd is a system and session manager for Linux, compatible with System V and LSB init scripts. The main features are:

  • provides aggressive parallelization capabilities

  • uses socket and D-Bus activation for starting services

  • offers on-demand starting of daemons

  • keeps track of processes using Linux cgroups

  • supports snapshotting and restoring of the system state

  • maintains mount and automount points

  • implements an elaborate transactional dependency-based service control logic

13.1.2 Unit File

A unit configuration file contains information about a service, a socket, a device, a mount point, an automount point, a swap file or partition, a start-up target, a watched file system path, a timer controlled and supervised by systemd, a temporary system state snapshot, a resource management slice or a group of externally created processes. Unit file is a generic term used by systemd for the following:

  • Service.  Information about a process (for example running a daemon); file ends with .service

  • Targets.  Used for grouping units and as synchronization points during start-up; file ends with .target

  • Sockets.  Information about an IPC or network socket or a file system FIFO, for socket-based activation (like inetd); file ends with .socket

  • Path.  Used to trigger other units (for example running a service when files change); file ends with .path

  • Timer.  Information about a timer controlled, for timer-based activation; file ends with .timer

  • Mount point.  Usually auto-generated by the fstab generator; file ends with .mount

  • Automount point.  Information about a file system automount point; file ends with .automount

  • Swap.  Information about a swap device or file for memory paging; file ends with .swap

  • Device.  Information about a device unit as exposed in the sysfs/udev(7) device tree; file ends with .device

  • Scope / Slice.  A concept for hierarchically managing resources of a group of processes; file ends with .scope/.slice

For more information about systemd.unit see http://www.freedesktop.org/software/systemd/man/systemd.unit.html

13.2 Basic Usage

The System V init system uses several commands to handle services—the init scripts, insserv, telinit and others. systemd makes it easier to manage services, since there is only one command to memorize for the majority of service-handling tasks: systemctl. It uses the command plus subcommand notation like git or zypper:

systemctl GENERAL OPTIONS SUBCOMMAND SUBCOMMAND OPTIONS

See man 1 systemctl for a complete manual.

Tip
Tip: Terminal Output and Bash Completion

If the output goes to a terminal (and not to a pipe or a file, for example) systemd commands send long output to a pager by default. Use the --no-pager option to turn off paging mode.

systemd also supports bash-completion, allowing you to enter the first letters of a subcommand and then press →| to automatically complete it. This feature is only available in the bash shell and requires the installation of the package bash-completion.

13.2.1 Managing Services in a Running System

Subcommands for managing services are the same as for managing a service with System V init (start, stop, ...). The general syntax for service management commands is as follows:

systemd
systemctl reload|restart|start|status|stop|... MY_SERVICE(S)
System V init
rcMY_SERVICE(S) reload|restart|start|status|stop|...

systemd allows you to manage several services in one go. Instead of executing init scripts one after the other as with System V init, execute a command like the following:

systemctl start MY_1ST_SERVICE MY_2ND_SERVICE

To list all services available on the system:

systemctl list-unit-files --type=service

The following table lists the most important service management commands for systemd and System V init:

Table 13.1: Service Management Commands

Task

systemd Command

System V init Command

Starting. 

start
start

Stopping. 

stop
stop

Restarting.  Shuts down services and starts them afterward. If a service is not yet running it will be started.

restart
restart

Restarting conditionally.  Restarts services if they are currently running. Does nothing for services that are not running.

try-restart
try-restart

Reloading.  Tells services to reload their configuration files without interrupting operation. Use case: Tell Apache to reload a modified httpd.conf configuration file. Note that not all services support reloading.

reload
reload

Reloading or restarting.  Reloads services if reloading is supported, otherwise restarts them. If a service is not yet running it will be started.

reload-or-restart
n/a

Reloading or restarting conditionally.  Reloads services if reloading is supported, otherwise restarts them if currently running. Does nothing for services that are not running.

reload-or-try-restart
n/a

Getting detailed status information.  Lists information about the status of services. The systemd command shows details such as description, executable, status, cgroup, and messages last issued by a service (see Section 13.6.8, “Debugging Services”). The level of details displayed with the System V init differs from service to service.

status
status

Getting short status information.  Shows whether services are active or not.

is-active
status

13.2.2 Permanently Enabling/Disabling Services

The service management commands mentioned in the previous section let you manipulate services for the current session. systemd also lets you permanently enable or disable services, so they are automatically started when requested or are always unavailable. You can either do this by using YaST, or on the command line.

13.2.2.1 Enabling/Disabling Services on the Command Line

The following table lists enabling and disabling commands for systemd and System V init:

Important
Important: Service Start

When enabling a service on the command line, it is not started automatically. It is scheduled to be started with the next system start-up or runlevel/target change. To immediately start a service after having enabled it, explicitly run systemctl start MY_SERVICE or rc MY_SERVICE start.

Table 13.2: Commands for Enabling and Disabling Services

Task

systemd Command

System V init Command

Enabling. 

systemctl enable MY_SERVICE(S)

insserv MY_SERVICE(S), chkconfig -a MY_SERVICE(S)

Disabling. 

systemctl disable MY_SERVICE(S).service

insserv -r MY_SERVICE(S), chkconfig -d MY_SERVICE(S)

Checking.  Shows whether a service is enabled or not.

systemctl is-enabled MY_SERVICE

chkconfig MY_SERVICE

Re-enabling.  Similar to restarting a service, this command first disables and then enables a service. Useful to re-enable a service with its defaults.

systemctl reenable MY_SERVICE

n/a

Masking.  After disabling a service, it can still be started manually. To completely disable a service, you need to mask it. Use with care.

systemctl mask MY_SERVICE

n/a

Unmasking.  A service that has been masked can only be used again after it has been unmasked.

systemctl unmask MY_SERVICE

n/a

13.3 System Start and Target Management

The entire process of starting the system and shutting it down is maintained by systemd. From this point of view, the kernel can be considered a background process to maintain all other processes and adjust CPU time and hardware access according to requests from other programs.

13.3.1 Targets Compared to Runlevels

With System V init the system was booted into a so-called Runlevel. A runlevel defines how the system is started and what services are available in the running system. Runlevels are numbered; the most commonly known ones are 0 (shutting down the system), 3 (multiuser with network) and 5 (multiuser with network and display manager).

systemd introduces a new concept by using so-called target units. However, it remains fully compatible with the runlevel concept. Target units are named rather than numbered and serve specific purposes. For example, the targets local-fs.target and swap.target mount local file systems and swap spaces.

The target graphical.target provides a multiuser system with network and display manager capabilities and is equivalent to runlevel 5. Complex targets, such as graphical.target act as meta targets by combining a subset of other targets. Since systemd makes it easy to create custom targets by combining existing targets, it offers great flexibility.

The following list shows the most important systemd target units. For a full list refer to man 7 systemd.special.

Selected systemd Target Units
default.target

The target that is booted by default. Not a real target, but rather a symbolic link to another target like graphic.target. Can be permanently changed via YaST (see Section 13.4, “Managing Services with YaST”). To change it for a session, use the kernel parameter systemd.unit=MY_TARGET.target at the boot prompt.

emergency.target

Starts an emergency shell on the console. Only use it at the boot prompt as systemd.unit=emergency.target.

graphical.target

Starts a system with network, multiuser support and a display manager.

halt.target

Shuts down the system.

mail-transfer-agent.target

Starts all services necessary for sending and receiving mails.

multi-user.target

Starts a multiuser system with network.

reboot.target

Reboots the system.

rescue.target

Starts a single-user system without network.

To remain compatible with the System V init runlevel system, systemd provides special targets named runlevelX.target mapping the corresponding runlevels numbered X.

If you want to know the current target, use the command: systemctl get-default

Table 13.3: System V Runlevels and systemd Target Units

System V runlevel

systemd target

Purpose

0

runlevel0.target, halt.target, poweroff.target

System shutdown

1, S

runlevel1.target, rescue.target,

Single-user mode

2

runlevel2.target, multi-user.target,

Local multiuser without remote network

3

runlevel3.target, multi-user.target,

Full multiuser with network

4

runlevel4.target

Unused/User-defined

5

runlevel5.target, graphical.target,

Full multiuser with network and display manager

6

runlevel6.target, reboot.target,

System reboot

Important
Important: systemd Ignores /etc/inittab

The runlevels in a System V init system are configured in /etc/inittab. systemd does not use this configuration. Refer to Section 13.5.3, “Creating Custom Targets” for instructions on how to create your own bootable target.

13.3.1.1 Commands to Change Targets

Use the following commands to operate with target units:

Task

systemd Command

System V init Command

Change the current target/runlevel

systemctl isolate MY_TARGET.target

telinit X

Change to the default target/runlevel

systemctl default

n/a

Get the current target/runlevel

systemctl list-units --type=target

With systemd there is usually more than one active target. The command lists all currently active targets.

who -r

or

runlevel

persistently change the default runlevel

Use the Services Manager or run the following command:

ln -sf /usr/lib/systemd/system/ MY_TARGET.target /etc/systemd/system/default.target

Use the Services Manager or change the line

id: X:initdefault:

in /etc/inittab

Change the default runlevel for the current boot process

Enter the following option at the boot prompt

systemd.unit= MY_TARGET.target

Enter the desired runlevel number at the boot prompt.

Show a target's/runlevel's dependencies

systemctl show -p "Requires" MY_TARGET.target

systemctl show -p "Wants" MY_TARGET.target

Requires lists the hard dependencies (the ones that must be resolved), whereas Wants lists the soft dependencies (the ones that get resolved if possible).

n/a

13.3.2 Debugging System Start-Up

systemd offers the means to analyze the system start-up process. You can review the list of all services and their status (rather than having to parse /varlog/). systemd also allows you to scan the start-up procedure to find out how much time each service start-up consumes.

13.3.2.1 Review Start-Up of Services

To review the complete list of services that have been started since booting the system, enter the command systemctl. It lists all active services like shown below (shortened). To get more information on a specific service, use systemctl status MY_SERVICE.

Example 13.1: List Active Services
root # systemctl
UNIT                        LOAD   ACTIVE SUB       JOB DESCRIPTION
[...]
iscsi.service               loaded active exited    Login and scanning of iSC+
kmod-static-nodes.service   loaded active exited    Create list of required s+
libvirtd.service            loaded active running   Virtualization daemon
nscd.service                loaded active running   Name Service Cache Daemon
ntpd.service                loaded active running   NTP Server Daemon
polkit.service              loaded active running   Authorization Manager
postfix.service             loaded active running   Postfix Mail Transport Ag+
rc-local.service            loaded active exited    /etc/init.d/boot.local Co+
rsyslog.service             loaded active running   System Logging Service
[...]
LOAD   = Reflects whether the unit definition was properly loaded.
ACTIVE = The high-level unit activation state, i.e. generalization of SUB.
SUB    = The low-level unit activation state, values depend on unit type.

161 loaded units listed. Pass --all to see loaded but inactive units, too.
To show all installed unit files use 'systemctl list-unit-files'.

To restrict the output to services that failed to start, use the --failed option:

Example 13.2: List Failed Services
root # systemctl --failed
UNIT                   LOAD   ACTIVE SUB    JOB DESCRIPTION
apache2.service        loaded failed failed     apache
NetworkManager.service loaded failed failed     Network Manager
plymouth-start.service loaded failed failed     Show Plymouth Boot Screen

[...]

13.3.2.2 Debug Start-Up Time

To debug system start-up time, systemd offers the systemd-analyze command. It shows the total start-up time, a list of services ordered by start-up time and can also generate an SVG graphic showing the time services took to start in relation to the other services.

Listing the System Start-Up Time
root # systemd-analyze
Startup finished in 2666ms (kernel) + 21961ms (userspace) = 24628ms
Listing the Services Start-Up Time
root # systemd-analyze blame
  6472ms systemd-modules-load.service
  5833ms remount-rootfs.service
  4597ms network.service
  4254ms systemd-vconsole-setup.service
  4096ms postfix.service
  2998ms xdm.service
  2483ms localnet.service
  2470ms SuSEfirewall2_init.service
  2189ms avahi-daemon.service
  2120ms systemd-logind.service
  1210ms xinetd.service
  1080ms ntp.service
[...]
    75ms fbset.service
    72ms purge-kernels.service
    47ms dev-vda1.swap
    38ms bluez-coldplug.service
    35ms splash_early.service
Services Start-Up Time Graphics
root # systemd-analyze plot > jupiter.example.com-startup.svg

13.3.2.3 Review the Complete Start-Up Process

The above-mentioned commands let you review the services that started and the time it took to start them. If you need to know more details, you can tell systemd to verbosely log the complete start-up procedure by entering the following parameters at the boot prompt:

systemd.log_level=debug systemd.log_target=kmsg

Now systemd writes its log messages into the kernel ring buffer. View that buffer with dmesg:

dmesg -T | less

13.3.3 System V Compatibility

systemd is compatible with System V, allowing you to still use existing System V init scripts. However, there is at least one known issue where a System V init script does not work with systemd out of the box: starting a service as a different user via su or sudo in init scripts will result in a failure of the script, producing an Access denied error.

When changing the user with su or sudo, a PAM session is started. This session will be terminated after the init script is finished. As a consequence, the service that has been started by the init script will also be terminated. To work around this error, proceed as follows:

  1. Create a service file wrapper with the same name as the init script plus the file name extension .service:

    [Unit]
    Description=DESCRIPTION
    After=network.target
    
    [Service]
    User=USER
    Type=forking1
    PIDFile=PATH TO PID FILE1
    ExecStart=PATH TO INIT SCRIPT start
    ExecStop=PATH TO INIT SCRIPT stop
    ExecStopPost=/usr/bin/rm -f PATH TO PID FILE1
    
    [Install]
    WantedBy=multi-user.target2

    Replace all values written in UPPERCASE LETTERS with appropriate values.

    1

    Optional—only use if the init script starts a daemon.

    2

    multi-user.target also starts the init script when booting into graphical.target. If it should only be started when booting into the display manager, user graphical.target here.

  2. Start the daemon with systemctl start APPLICATION.

13.4 Managing Services with YaST

Basic service management can also be done with the YaST Services Manager module. It supports starting, stopping, enabling and disabling services. It also lets you show a service's status and change the default target. Start the YaST module with YaST › System › Services Manager.

Services Manager
Figure 13.1: Services Manager
Changing the Default System Target

To change the target the system boots into, choose a target from the Default System Target drop-down box. The most often used targets are Graphical Interface (starting a graphical login screen) and Multi-User (starting the system in command line mode).

Starting or Stopping a Service

Select a service from the table. The Active column shows whether it is currently running (Active) or not (Inactive). Toggle its status by choosing Start/Stop.

Starting or stopping a service changes its status for the currently running session. To change its status throughout a reboot, you need to enable or disable it.

Enabling or Disabling a Service

Select a service from the table. The Enabled column shows whether it is currently Enabled or Disabled. Toggle its status by choosing Enable/Disable.

By enabling or disabling a service you configure whether it is started during booting (Enabled) or not (Disabled). This setting will not affect the current session. To change its status in the current session, you need to start or stop it.

View a Status Messages

To view the status message of a service, select it from the list and choose Show Details. The output you will see is identical to the one generated by the command systemctl -l status MY_SERVICE.

Warning
Warning: Faulty Runlevel Settings May Damage Your System

Faulty runlevel settings may make your system unusable. Before applying your changes, make absolutely sure that you know their consequences.

13.5 Customization of systemd

The following sections contain some examples for systemd customization.

Warning
Warning: Avoiding Overwritten Customization

Always do systemd customization in /etc/systemd/, never in /usr/lib/systemd/. Otherwise your changes will be overwritten by the next update of systemd.

13.5.1 Customizing Service Files

The systemd service files are located in /usr/lib/systemd/system. If you want to customize them, proceed as follows:

  1. Copy the files you want to modify from /usr/lib/systemd/system to /etc/systemd/system. Keep the file names identical to the original ones.

  2. Modify the copies in /etc/systemd/system according to your needs.

  3. For an overview of your configuration changes, use the systemd-delta command. It can compare and identify configuration files that override other configuration files. For details, refer to the systemd-delta man page.

The modified files in /etc/systemd will take precedence over the original files in /usr/lib/systemd/system, provided that their file name is the same.

13.5.2 Creating Drop-in Files

If you only want to add a few lines to a configuration file or modify a small part of it, you can use so-called drop-in files. Drop-in files let you extend the configuration of unit files without having to edit or override the unit files themselves.

For example, to change one value for the FOOBAR service located in /usr/lib/systemd/system/FOOBAR.SERVICE, proceed as follows:

  1. Create a directory called /etc/systemd/system/MY_SERVICE.service.d/.

    Note the .d suffix. The directory must otherwise be named like the service that you want to patch with the drop-in file.

  2. In that directory, create a file WHATEVERMODIFICATION.conf.

    Make sure it only contains the line with the value that you want to modify.

  3. Save your changes to the file. It will be used as an extension of the original file.

13.5.3 Creating Custom Targets

On System V init SUSE systems, runlevel 4 is unused to allow administrators to create their own runlevel configuration. systemd allows you to create any number of custom targets. It is suggested to start by adapting an existing target such as graphical.target.

  1. Copy the configuration file /usr/lib/systemd/system/graphical.target to /etc/systemd/system/MY_TARGET.target and adjust it according to your needs.

  2. The configuration file copied in the previous step already covers the required (hard) dependencies for the target. To also cover the wanted (soft) dependencies, create a directory /etc/systemd/system/MY_TARGET.target.wants.

  3. For each wanted service, create a symbolic link from /usr/lib/systemd/system into /etc/systemd/system/MY_TARGET.target.wants.

  4. Once you have finished setting up the target, reload the systemd configuration to make the new target available:

    systemctl daemon-reload

13.6 Advanced Usage

The following sections cover advanced topics for system administrators. For even more advanced systemd documentation, refer to Lennart Pöttering's series about systemd for administrators at http://0pointer.de/blog/projects.

13.6.1 Cleaning Temporary Directories

systemd supports cleaning temporary directories regularly. The configuration from the previous system version is automatically migrated and active. tmpfiles.d—which is responsible for managing temporary files—reads its configuration from /etc/tmpfiles.d/*.conf , /run/tmpfiles.d/*.conf, and /usr/lib/tmpfiles.d/*.conf files. Configuration placed in /etc/tmpfiles.d/*.conf overrides related configurations from the other two directories (/usr/lib/tmpfiles.d/*.conf is where packages store their configuration files).

The configuration format is one line per path containing action and path, and optionally mode, ownership, age and argument fields, depending on the action. The following example unlinks the X11 lock files:

Type Path               Mode UID  GID  Age Argument
r    /tmp/.X[0-9]*-lock

To get the status the tmpfile timer:

systemctl status systemd-tmpfiles-clean.timer
systemd-tmpfiles-clean.timer - Daily Cleanup of Temporary Directories
 Loaded: loaded (/usr/lib/systemd/system/systemd-tmpfiles-clean.timer; static)
 Active: active (waiting) since Tue 2014-09-09 15:30:36 CEST; 1 weeks 6 days ago
   Docs: man:tmpfiles.d(5)
         man:systemd-tmpfiles(8)

Sep 09 15:30:36 jupiter systemd[1]: Starting Daily Cleanup of Temporary Directories.
Sep 09 15:30:36 jupiter systemd[1]: Started Daily Cleanup of Temporary Directories.

For more information on temporary files handling, see man 5 tmpfiles.d.

13.6.2 System Log

Section 13.6.8, “Debugging Services” explains how to view log messages for a given service. However, displaying log messages is not restricted to service logs. You can also access and query the complete log messages written by systemd—the so-called Journal. Use the command systemd-journalctl to display the complete log messages starting with the oldest entries. Refer to man 1 systemd-journalctl for options such as applying filters or changing the output format.

13.6.3 Snapshots

You can save the current state of systemd to a named snapshot and later revert to it with the isolate subcommand. This is useful when testing services or custom targets, because it allows you to return to a defined state at any time. A snapshot is only available in the current session and will automatically be deleted on reboot. A snapshot name must end in .snapshot.

Create a Snapshot
systemctl snapshot MY_SNAPSHOT.snapshot
Delete a Snapshot
systemctl delete MY_SNAPSHOT.snapshot
View a Snapshot
systemctl show MY_SNAPSHOT.snapshot
Activate a Snapshot
systemctl isolate MY_SNAPSHOT.snapshot

13.6.4 Loading Kernel Modules

With systemd, kernel modules can automatically be loaded at boot time via a configuration file in /etc/modules-load.d. The file should be named MODULE.conf and have the following content:

# load module MODULE at boot time
MODULE

In case a package installs a configuration file for loading a kernel module, the file gets installed to /usr/lib/modules-load.d. If two configuration files with the same name exist, the one in /etc/modules-load.d tales precedence.

For more information, see the modules-load.d(5) man page.

13.6.5 Performing Actions before Loading a Service

With System V init actions that need to be performed before loading a service, needed to be specified in /etc/init.d/before.local . This procedure is no longer supported with systemd. If you need to do actions before starting services, do the following:

Loading Kernel Modules

Create a drop-in file in /etc/modules-load.d directory (see man modules-load.d for the syntax)

Creating Files or Directories, Cleaning-up Directories, Changing Ownership

Create a drop-in file in /etc/tmpfiles.d (see man tmpfiles.d for the syntax)

Other Tasks

Create a system service file, for example /etc/systemd/system/before.service, from the following template:

[Unit]
Before=NAME OF THE SERVICE YOU WANT THIS SERVICE TO BE STARTED BEFORE
[Service]
Type=oneshot
RemainAfterExit=true
ExecStart=YOUR_COMMAND
# beware, executable is run directly, not through a shell, check the man pages
# systemd.service and systemd.unit for full syntax
[Install]
# target in which to start the service
WantedBy=multi-user.target
#WantedBy=graphical.target

When the service file is created, you should run the following commands (as root):

systemctl daemon-reload
systemctl enable before

Every time you modify the service file, you need to run:

systemctl daemon-reload

13.6.6 Kernel Control Groups (cgroups)

On a traditional System V init system it is not always possible to clearly assign a process to the service that spawned it. Some services, such as Apache, spawn a lot of third-party processes (for example CGI or Java processes), which themselves spawn more processes. This makes a clear assignment difficult or even impossible. Additionally, a service may not terminate correctly, leaving some children alive.

systemd solves this problem by placing each service into its own cgroup. cgroups are a kernel feature that allows aggregating processes and all their children into hierarchical organized groups. systemd names each cgroup after its service. Since a non-privileged process is not allowed to leave its cgroup, this provides an effective way to label all processes spawned by a service with the name of the service.

To list all processes belonging to a service, use the command systemd-cgls. The result will look like the following (shortened) example:

Example 13.3: List all Processes Belonging to a Service
root # systemd-cgls --no-pager
├─1 /usr/lib/systemd/systemd --switched-root --system --deserialize 20
├─user.slice
│ └─user-1000.slice
│   ├─session-102.scope
│   │ ├─12426 gdm-session-worker [pam/gdm-password]
│   │ ├─15831 gdm-session-worker [pam/gdm-password]
│   │ ├─15839 gdm-session-worker [pam/gdm-password]
│   │ ├─15858 /usr/lib/gnome-terminal-server

[...]

└─system.slice
  ├─systemd-hostnamed.service
  │ └─17616 /usr/lib/systemd/systemd-hostnamed
  ├─cron.service
  │ └─1689 /usr/sbin/cron -n
  ├─ntpd.service
  │ └─1328 /usr/sbin/ntpd -p /var/run/ntp/ntpd.pid -g -u ntp:ntp -c /etc/ntp.conf
  ├─postfix.service
  │ ├─ 1676 /usr/lib/postfix/master -w
  │ ├─ 1679 qmgr -l -t fifo -u
  │ └─15590 pickup -l -t fifo -u
  ├─sshd.service
  │ └─1436 /usr/sbin/sshd -D

[...]

See Chapter 9, Kernel Control Groups for more information about cgroups.

13.6.7 Terminating Services (Sending Signals)

As explained in Section 13.6.6, “Kernel Control Groups (cgroups)”, it is not always possible to assign a process to its parent service process in a System V init system. This makes it difficult to terminate a service and all of its children. Child processes that have not been terminated will remain as zombie processes.

systemd's concept of confining each service into a cgroup makes it possible to clearly identify all child processes of a service and therefore allows you to send a signal to each of these processes. Use systemctl kill to send signals to services. For a list of available signals refer to man 7 signals.

Sending SIGTERM to a Service

SIGTERM is the default signal that is sent.

systemctl kill MY_SERVICE
Sending SIGNAL to a Service

Use the -s option to specify the signal that should be sent.

systemctl kill -s SIGNAL MY_SERVICE
Selecting Processes

By default the kill command sends the signal to all processes of the specified cgroup. You can restrict it to the control or the main process. The latter is for example useful to force a service to reload its configuration by sending SIGHUP:

systemctl kill -s SIGHUP --kill-who=main MY_SERVICE
Warning
Warning: Terminating or Restarting the D-Bus Service is Not Supported

The D-Bus service is the message bus for communication between systemd clients and the systemd manager that is running as pid 1. Even though dbus is a stand-alone daemon, it is an integral part of the init infrastructure.

Terminating dbus or restarting it in the running system is similar to an attempt to terminate or restart pid 1. It will break systemd client/server communication and make most systemd functions unusable.

Therefore, terminating or restarting dbus is neither recommended nor supported.

13.6.8 Debugging Services

By default, systemd is not overly verbose. If a service was started successfully, no output will be produced. In case of a failure, a short error message will be displayed. However, systemctl status provides means to debug start-up and operation of a service.

systemd comes with its own logging mechanism (The Journal) that logs system messages. This allows you to display the service messages together with status messages. The status command works similar to tail and can also display the log messages in different formats, making it a powerful debugging tool.

Show Service Start-Up Failure

Whenever a service fails to start, use systemctl status MY_SERVICE to get a detailed error message:

root # systemctl start apache2
Job failed. See system journal and 'systemctl status' for details.
root # systemctl status apache2
   Loaded: loaded (/usr/lib/systemd/system/apache2.service; disabled)
   Active: failed (Result: exit-code) since Mon, 04 Jun 2012 16:52:26 +0200; 29s ago
   Process: 3088 ExecStart=/usr/sbin/start_apache2 -D SYSTEMD -k start (code=exited, status=1/FAILURE)
   CGroup: name=systemd:/system/apache2.service

Jun 04 16:52:26 g144 start_apache2[3088]: httpd2-prefork: Syntax error on line
205 of /etc/apache2/httpd.conf: Syntax error on li...alHost>
Show Last N Service Messages

The default behavior of the status subcommand is to display the last ten messages a service issued. To change the number of messages to show, use the --lines=N parameter:

systemctl status ntp
systemctl --lines=20 status ntp
Show Service Messages in Append Mode

To display a live stream of service messages, use the --follow option, which works like tail -f:

systemctl --follow status ntp
Messages Output Format

The --output=MODE parameter allows you to change the output format of service messages. The most important modes available are:

short

The default format. Shows the log messages with a human readable time stamp.

verbose

Full output with all fields.

cat

Terse output without time stamps.

13.7 More Information

For more information on systemd refer to the following online resources:

Homepage

http://www.freedesktop.org/wiki/Software/systemd

systemd for Administrators

Lennart Pöttering, one of the systemd authors, has written a series of blog entries (13 at the time of writing this chapter). Find them at http://0pointer.de/blog/projects.

Part III System

14 32-Bit and 64-Bit Applications in a 64-Bit System Environment

SUSE® Linux Enterprise Server is available for several 64-bit platforms. This does not necessarily mean that all the applications included have already been ported to 64-bit platforms. SUSE Linux Enterprise Server supports the use of 32-bit applications in a 64-bit system environment. This chapter o…

15 journalctl: Query the systemd Journal

When systemd replaced traditional init scripts in SUSE Linux Enterprise 12 (see Chapter 13, The systemd Daemon), it introduced its own logging system called journal. There is no need to run a syslog based service anymore, as all system events are written in the journal.

16 Basic Networking

Linux offers the necessary networking tools and features for integration into all types of network structures. Network access using a network card can be configured with YaST. Manual configuration is also possible. In this chapter only the fundamental mechanisms and the relevant network configuration files are covered.

17 Printer Operation

SUSE® Linux Enterprise Server supports printing with many types of printers, including remote network printers. Printers can be configured manually or with YaST. For configuration instructions, refer to Section 11.3, “Setting Up a Printer”. Both graphical and command line utilities are available for…

18 The X Window System

The X Window System (X11) is the de facto standard for graphical user interfaces in Unix. X is network-based, enabling applications started on one host to be displayed on another host connected over any kind of network (LAN or Internet). This chapter provides basic information on the X configuration…

19 Accessing File Systems with FUSE

FUSE is the acronym for file system in user space. This means you can configure and mount a file system as an unprivileged user. Normally, you need to be root for this task. FUSE alone is a kernel module. Combined with plug-ins, it allows you to extend FUSE to access almost all file systems like remote SSH connections, ISO images, and more.

20 Managing Kernel Modules

Although Linux is a monolithic kernel, it can be extended using kernel modules. These are special objects that can be inserted into the kernel and removed on demand. In practical terms, kernel modules make it possible to add and remove drivers and interfaces that are not included in the kernel itsel…

21 Dynamic Kernel Device Management with udev

The kernel can add or remove almost any device in a running system. Changes in the device state (whether a device is plugged in or removed) need to be propagated to user space. Devices need to be configured when they are plugged in and recognized. Users of a certain device need to be informed about …

22 Live Patching the Linux Kernel Using kGraft

This document describes the basic principles of the kGraft live patching technology and provides usage guidelines for the SLE Live Patching service.

kGraft is a live patching technology for runtime patching of the Linux kernel, without stopping the kernel. This maximizes system uptime, and thus system availability, which is important for mission-critical systems. By allowing dynamic patching of the kernel, the technology also encourages users to install critical security updates without deferring them to a scheduled downtime.

A kGraft patch is a kernel module, intended for replacing whole functions in the kernel. kGraft primarily offers in-kernel infrastructure for integration of the patched code with base kernel code at runtime.

SLE Live Patching is a service provided on top of regular SUSE Linux Enterprise Server maintenance. kGraft patches distributed through SLE Live Patching supplement regular SLES maintenance updates. Common update stack and procedures can be used for SLE Live Patching deployment.

The information provided in this document related to the AMD64/Intel 64 and POWER architectures. In case you use a different architecture, the procedures may differ.

23 Special System Features

This chapter starts with information about various software packages, the virtual consoles and the keyboard layout. We talk about software components like bash, cron and logrotate, because they were changed or enhanced during the last release cycles. Even if they are small or considered of minor importance, users should change their default behavior, because these components are often closely coupled with the system. The chapter concludes with a section about language and country-specific settings (I18N and L10N).

14 32-Bit and 64-Bit Applications in a 64-Bit System Environment

  • Filename: 64bit_issues.xml
  • ID: cha.64bit

SUSE® Linux Enterprise Server is available for several 64-bit platforms. This does not necessarily mean that all the applications included have already been ported to 64-bit platforms. SUSE Linux Enterprise Server supports the use of 32-bit applications in a 64-bit system environment. This chapter offers a brief overview of how this support is implemented on 64-bit SUSE Linux Enterprise Server platforms. It explains how 32-bit applications are executed and how 32-bit applications should be compiled to enable them to run both in 32-bit and 64-bit system environments. Additionally, find information about the kernel API and an explanation of how 32-bit applications can run under a 64-bit kernel.

SUSE Linux Enterprise Server for the 64-bit platforms POWER, z Systems and AMD64/Intel 64 is designed so that existing 32-bit applications run in the 64-bit environment out-of-the-box. The corresponding 32-bit platforms are ppc for POWER, and x86 for AMD64/Intel 64. This support means that you can continue to use your preferred 32-bit applications without waiting for a corresponding 64-bit port to become available. The current POWER system runs most applications in 32-bit mode, but you can run 64-bit applications.

14.1 Runtime Support

Important
Important: Conflicts Between Application Versions

If an application is available both for 32-bit and 64-bit environments, parallel installation of both versions is bound to lead to problems. In such cases, decide on one of the two versions and install and use this.

An exception to this rule is PAM (pluggable authentication modules). SUSE Linux Enterprise Server uses PAM in the authentication process as a layer that mediates between user and application. On a 64-bit operating system that also runs 32-bit applications it is necessary to always install both versions of a PAM module.

To be executed correctly, every application requires a range of libraries. Unfortunately, the names for the 32-bit and 64-bit versions of these libraries are identical. They must be differentiated from each other in another way.

To retain compatibility with the 32-bit version, the libraries are stored at the same place in the system as in the 32-bit environment. The 32-bit version of libc.so.6 is located under /lib/libc.so.6 in both the 32-bit and 64-bit environments.

All 64-bit libraries and object files are located in directories called lib64. The 64-bit object files that you would normally expect to find under /lib and /usr/lib are now found under /lib64 and /usr/lib64. This means that there is space for the 32-bit libraries under /lib and /usr/lib, so the file name for both versions can remain unchanged.

Subdirectories of 32-bit /lib directories which contain data content that does not depend on the word size are not moved. This scheme conforms to LSB (Linux Standards Base) and FHS (File System Hierarchy Standard).

14.2 Software Development

All 64-bit architectures support the development of 64-bit objects. The level of support for 32-bit compiling depends on the architecture. These are the various implementation options for the toolchain from GCC (GNU Compiler Collection) and binutils, which include the assembler as and the linker ld:

Both 32-bit and 64-bit objects can be generated with a biarch development toolchain. A biarch development toolchain allows generation of 32-bit and 64-bit objects. The compilation of 64-bit objects is the default on almost all platforms. 32-bit objects can be generated if special flags are used. This special flag is -m32 for GCC. The flags for the binutils are architecture-dependent, but GCC transfers the correct flags to linkers and assemblers. A biarch development toolchain currently exists for amd64 (supports development for x86 and amd64 instructions), for z Systems and for POWER. 32-bit objects are normally created on the POWER platform. The -m64 flag must be used to generate 64-bit objects.

All header files must be written in an architecture-independent form. The installed 32-bit and 64-bit libraries must have an API (application programming interface) that matches the installed header files. The normal SUSE Linux Enterprise Server environment is designed according to this principle. In the case of manually updated libraries, resolve these issues yourself.

14.3 Software Compilation on Biarch Platforms

To develop binaries for the other architecture on a biarch architecture, the respective libraries for the second architecture must additionally be installed. These packages are called rpmname-32bit or rpmname-x86 if the second architecture is a 32-bit architecture or rpmname-64bit if the second architecture is a 64-bit architecture. You also need the respective headers and libraries from the rpmname-devel packages and the development libraries for the second architecture from rpmname-devel-32bit or rpmname-devel-64bit.

For example, to compile a program that uses libaio on a system with a 32-bit second architecture (x86_64 or z Systems), you need the following RPMs:

libaio-32bit

32-bit runtime package

libaio-devel-32bit

Headers and libraries for 32-bit development

libaio

64-bit runtime package

libaio-devel

64-bit development headers and libraries

Most open source programs use an autoconf-based program configuration. To use autoconf for configuring a program for the second architecture, overwrite the normal compiler and linker settings of autoconf by running the configure script with additional environment variables.

The following example refers to an x86_64 system with x86 as the second architecture. Examples for POWER with ppc as the second architecture would be similar.

  1. Use the 32-bit compiler:

    CC="gcc -m32"
  2. Instruct the linker to process 32-bit objects (always use gcc as the linker front-end):

    LD="gcc -m32"
  3. Set the assembler to generate 32-bit objects:

    AS="gcc -c -m32"
  4. Specify linker flags, such as the location of 32-bit libraries, for example:

    LDFLAGS="-L/usr/lib"
  5. Specify the location for the 32-bit object code libraries:

    --libdir=/usr/lib
  6. Specify the location for the 32-bit X libraries:

    --x-libraries=/usr/lib

Not all of these variables are needed for every program. Adapt them to the respective program.

An example configure call to compile a native 32-bit application on x86_64, POWER or z Systems could appear as follows:

CC="gcc -m32"
LDFLAGS="-L/usr/lib;"
./configure --prefix=/usr --libdir=/usr/lib --x-libraries=/usr/lib
make
make install

14.4 Kernel Specifications

The 64-bit kernels for AMD64/Intel 64, POWER and z Systems offer both a 64-bit and a 32-bit kernel ABI (application binary interface). The latter is identical with the ABI for the corresponding 32-bit kernel. This means that the 32-bit application can communicate with the 64-bit kernel in the same way as with the 32-bit kernel.

The 32-bit emulation of system calls for a 64-bit kernel does not support all the APIs used by system programs. This depends on the platform. For this reason, few applications, like lspci, must be compiled on non-POWER platforms as 64-bit programs to function properly. On IBM z Systems, not all ioctls are available in the 32-bit kernel ABI.

A 64-bit kernel can only load 64-bit kernel modules that have been specially compiled for this kernel. It is not possible to use 32-bit kernel modules.

Tip
Tip: Kernel-loadable Modules

Some applications require separate kernel-loadable modules. If you intend to use such a 32-bit application in a 64-bit system environment, contact the provider of this application and SUSE to make sure that the 64-bit version of the kernel-loadable module and the 32-bit compiled version of the kernel API are available for this module.

15 journalctl: Query the systemd Journal

  • Filename: journalctl.xml
  • ID: cha.journalctl

When systemd replaced traditional init scripts in SUSE Linux Enterprise 12 (see Chapter 13, The systemd Daemon), it introduced its own logging system called journal. There is no need to run a syslog based service anymore, as all system events are written in the journal.

The journal itself is a system service managed by systemd. Its full name is systemd-journald.service. It collects and stores logging data by maintaining structured indexed journals based on logging information received from the kernel, user processes, standard input, and system service errors. The systemd-journald service is on by default:

# systemctl status systemd-journald
systemd-journald.service - Journal Service
   Loaded: loaded (/usr/lib/systemd/system/systemd-journald.service; static)
   Active: active (running) since Mon 2014-05-26 08:36:59 EDT; 3 days ago
     Docs: man:systemd-journald.service(8)
           man:journald.conf(5)
 Main PID: 413 (systemd-journal)
   Status: "Processing requests..."
   CGroup: /system.slice/systemd-journald.service
           └─413 /usr/lib/systemd/systemd-journald
[...]

15.1 Making the Journal Persistent

The journal stores log data in /run/log/journal/ by default. Because the /run/ directory is volatile by nature, log data is lost at reboot. To make the log data persistent, the directory /var/log/journal/ with correct ownership and permissions must exist, where the systemd-journald service can store its data. systemd will create the directory for you—and switch to persistent logging—if you do the following:

  1. As root, open /etc/systemd/journald.conf for editing.

    # vi /etc/systemd/journald.conf
  2. Uncomment the line containing Storage= and change it to

    [...]
    [Journal]
    Storage=persistent
    #Compress=yes
    [...]
  3. Save the file and restart systemd-journald:

    systemctl restart systemd-journald

15.2 journalctl Useful Switches

This section introduces several common useful options to enhance the default journalctl behavior. All switches are described in the journalctl manual page, man 1 journalctl.

Tip
Tip: Messages Related to a Specific Executable

To show all journal messages related to a specific executable, specify the full path to the executable:

journalctl /usr/lib/systemd/systemd
-f

Shows only the most recent journal messages, and prints new log entries as they are added to the journal.

-e

Prints the messages and jumps to the end of the journal, so that the latest entries are visible within the pager.

-r

Prints the messages of the journal in reverse order, so that the latest entries are listed first.

-k

Shows only kernel messages. This is equivalent to the field match _TRANSPORT=kernel (see Section 15.3.3, “Filtering Based on Fields”).

-u

Shows only messages for the specified systemd unit. This is equivalent to the field match _SYSTEMD_UNIT=UNIT (see Section 15.3.3, “Filtering Based on Fields”).

# journalctl -u apache2
[...]
Jun 03 10:07:11 pinkiepie systemd[1]: Starting The Apache Webserver...
Jun 03 10:07:12 pinkiepie systemd[1]: Started The Apache Webserver.

15.3 Filtering the Journal Output

When called without switches, journalctl shows the full content of the journal, the oldest entries listed first. The output can be filtered by specific switches and fields.

15.3.1 Filtering Based on a Boot Number

journalctl can filter messages based on a specific system boot. To list all available boots, run

# journalctl --list-boots
-1 097ed2cd99124a2391d2cffab1b566f0 Mon 2014-05-26 08:36:56 EDT—Fri 2014-05-30 05:33:44 EDT
 0 156019a44a774a0bb0148a92df4af81b Fri 2014-05-30 05:34:09 EDT—Fri 2014-05-30 06:15:01 EDT

The first column lists the boot offset: 0 for the current boot, -1 for the previous one, -2 for the one prior to that, etc. The second column contains the boot ID followed by the limiting time stamps of the specific boot.

Show all messages from the current boot:

# journalctl -b

If you need to see journal messages from the previous boot, add an offset parameter. The following example outputs the previous boot messages:

# journalctl -b -1

Another way is to list boot messages based on the boot ID. For this purpose, use the _BOOT_ID field:

# journalctl _BOOT_ID=156019a44a774a0bb0148a92df4af81b

15.3.2 Filtering Based on Time Interval

You can filter the output of journalctl by specifying the starting and/or ending date. The date specification should be of the format "2014-06-30 9:17:16". If the time part is omitted, midnight is assumed. If seconds are omitted, ":00" is assumed. If the date part is omitted, the current day is assumed. Instead of numeric expression, you can specify the keywords "yesterday", "today", or "tomorrow". They refer to midnight of the day before the current day, of the current day, or of the day after the current day. If you specify "now", it refers to the current time. You can also specify relative times prefixed with - or +, referring to times before or after the current time.

Show only new messages since now, and update the output continuously:

# journalctl --since "now" -f

Show all messages since last midnight till 3:20am:

# journalctl --since "today" --until "3:20"

15.3.3 Filtering Based on Fields

You can filter the output of the journal by specific fields. The syntax of a field to be matched is FIELD_NAME=MATCHED_VALUE, such as _SYSTEMD_UNIT=httpd.service. You can specify multiple matches in a single query to filter the output messages even more. See man 7 systemd.journal-fields for a list of default fields.

Show messages produced by a specific process ID:

# journalctl _PID=1039

Show messages belonging to a specific user ID:

# journalctl _UID=1000

Show messages from the kernel ring buffer (the same as dmesg produces):

# journalctl _TRANSPORT=kernel

Show messages from the service's standard or error output:

# journalctl _TRANSPORT=stdout

Show messages produced by a specified service only:

# journalctl _SYSTEMD_UNIT=avahi-daemon.service

If two different fields are specified, only entries that match both expressions at the same time are shown:

# journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=1488

If two matches refer to the same field, all entries matching either expression are shown:

# journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service

You can use the '+' separator to combine two expressions in a logical 'OR'. The following example shows all messages from the Avahi service process with the process ID 1480 together with all messages from the D-Bus service:

# journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=1480 + _SYSTEMD_UNIT=dbus.service

15.4 Investigating systemd Errors

This section introduces a simple example to illustrate how to find and fix the error reported by systemd during apache2 start-up.

  1. Try to start the apache2 service:

    # systemctl start apache2
    Job for apache2.service failed. See 'systemctl status apache2' and 'journalctl -xn' for details.
  2. Let us see what the service's status says:

    # systemctl status apache2
    apache2.service - The Apache Webserver
       Loaded: loaded (/usr/lib/systemd/system/apache2.service; disabled)
       Active: failed (Result: exit-code) since Tue 2014-06-03 11:08:13 CEST; 7min ago
      Process: 11026 ExecStop=/usr/sbin/start_apache2 -D SYSTEMD -DFOREGROUND \
               -k graceful-stop (code=exited, status=1/FAILURE)

    The ID of the process causing the failure is 11026.

  3. Show the verbose version of messages related to process ID 11026:

    # journalctl -o verbose _PID=11026
    [...]
    MESSAGE=AH00526: Syntax error on line 6 of /etc/apache2/default-server.conf:
    [...]
    MESSAGE=Invalid command 'DocumenttRoot', perhaps misspelled or defined by a module
    [...]
  4. Fix the typo inside /etc/apache2/default-server.conf, start the apache2 service, and print its status:

    # systemctl start apache2 && systemctl status apache2
    apache2.service - The Apache Webserver
       Loaded: loaded (/usr/lib/systemd/system/apache2.service; disabled)
       Active: active (running) since Tue 2014-06-03 11:26:24 CEST; 4ms ago
      Process: 11026 ExecStop=/usr/sbin/start_apache2 -D SYSTEMD -DFOREGROUND
               -k graceful-stop (code=exited, status=1/FAILURE)
     Main PID: 11263 (httpd2-prefork)
       Status: "Processing requests..."
       CGroup: /system.slice/apache2.service
               ├─11263 /usr/sbin/httpd2-prefork -f /etc/apache2/httpd.conf -D [...]
               ├─11280 /usr/sbin/httpd2-prefork -f /etc/apache2/httpd.conf -D [...]
               ├─11281 /usr/sbin/httpd2-prefork -f /etc/apache2/httpd.conf -D [...]
               ├─11282 /usr/sbin/httpd2-prefork -f /etc/apache2/httpd.conf -D [...]
               ├─11283 /usr/sbin/httpd2-prefork -f /etc/apache2/httpd.conf -D [...]
               └─11285 /usr/sbin/httpd2-prefork -f /etc/apache2/httpd.conf -D [...]

15.5 Journald Configuration

The behavior of the systemd-journald service can be adjusted by modifying /etc/systemd/journald.conf. This section introduces only basic option settings. For a complete file description, see man 5 journald.conf. Note that you need to restart the journal for the changes to take effect with

# systemctl restart systemd-journald

15.5.1 Changing the Journal Size Limit

If the journal log data is saved to a persistent location (see Section 15.1, “Making the Journal Persistent”), it uses up to 10% of the file system the /var/log/journal resides on. For example, if /var/log/journal is located on a 30 GB /var partition, the journal may use up to 3 GB of the disk space. To change this limit, change (and uncomment) the SystemMaxUse option:

SystemMaxUse=50M

15.5.2 Forwarding the Journal to /dev/ttyX

You can forward the journal to a terminal device to inform you about system messages on a preferred terminal screen, for example /dev/tty12. Change the following journald options to

ForwardToConsole=yes
TTYPath=/dev/tty12

15.5.3 Forwarding the Journal to Syslog Facility

Journald is backward compatible with traditional syslog implementations such as rsyslog. Make sure the following is valid:

  • rsyslog is installed.

    # rpm -q rsyslog
    rsyslog-7.4.8-2.16.x86_64
  • rsyslog service is enabled.

    # systemctl is-enabled rsyslog
    enabled
  • Forwarding to syslog is enabled in /etc/systemd/journald.conf.

    ForwardToSyslog=yes

15.6 Using YaST to Filter the systemd Journal

For an easy way of filtering the systemd journal (without having to deal with the journalctl syntax), you can use the YaST journal module. After installing it with sudo zypper in yast2-journal, start it from YaST by selecting System › Systemd Journal. Alternatively, start it from command line by entering sudo yast2 journal.

YaST systemd Journal
Figure 15.1: YaST systemd Journal

The module displays the log entries in a table. The search box on top allows you to search for entries that contain certain characters, similar to using grep. To filter the entries by date and time, unit, file, or priority, click Change filters and set the respective options.

16 Basic Networking

  • Filename: net_basic.xml
  • ID: cha.basicnet
Abstract

Linux offers the necessary networking tools and features for integration into all types of network structures. Network access using a network card can be configured with YaST. Manual configuration is also possible. In this chapter only the fundamental mechanisms and the relevant network configuration files are covered.

Linux and other Unix operating systems use the TCP/IP protocol. It is not a single network protocol, but a family of network protocols that offer various services. The protocols listed in Several Protocols in the TCP/IP Protocol Family, are provided for exchanging data between two machines via TCP/IP. Networks combined by TCP/IP, comprising a worldwide network, are also called the Internet.

RFC stands for Request for Comments. RFCs are documents that describe various Internet protocols and implementation procedures for the operating system and its applications. The RFC documents describe the setup of Internet protocols. For more information about RFCs, see http://www.ietf.org/rfc.html.

Several Protocols in the TCP/IP Protocol Family
TCP

Transmission Control Protocol: a connection-oriented secure protocol. The data to transmit is first sent by the application as a stream of data and converted into the appropriate format by the operating system. The data arrives at the respective application on the destination host in the original data stream format it was initially sent. TCP determines whether any data has been lost or jumbled during the transmission. TCP is implemented wherever the data sequence matters.

UDP

User Datagram Protocol: a connectionless, insecure protocol. The data to transmit is sent in the form of packets generated by the application. The order in which the data arrives at the recipient is not guaranteed and data loss is possible. UDP is suitable for record-oriented applications. It features a smaller latency period than TCP.

ICMP

Internet Control Message Protocol: This is not a protocol for the end user, but a special control protocol that issues error reports and can control the behavior of machines participating in TCP/IP data transfer. In addition, it provides a special echo mode that can be viewed using the program ping.

IGMP

Internet Group Management Protocol: This protocol controls machine behavior when implementing IP multicast.

As shown in Figure 16.1, “Simplified Layer Model for TCP/IP”, data exchange takes place in different layers. The actual network layer is the insecure data transfer via IP (Internet protocol). On top of IP, TCP (transmission control protocol) guarantees, to a certain extent, security of the data transfer. The IP layer is supported by the underlying hardware-dependent protocol, such as Ethernet.

Simplified Layer Model for TCP/IP
Figure 16.1: Simplified Layer Model for TCP/IP

The diagram provides one or two examples for each layer. The layers are ordered according to abstraction levels. The lowest layer is very close to the hardware. The uppermost layer, however, is almost a complete abstraction from the hardware. Every layer has its own special function. The special functions of each layer are mostly implicit in their description. The data link and physical layers represent the physical network used, such as Ethernet.

Almost all hardware protocols work on a packet-oriented basis. The data to transmit is collected into packets (it cannot be sent all at once). The maximum size of a TCP/IP packet is approximately 64 KB. Packets are normally quite smaller, as the network hardware can be a limiting factor. The maximum size of a data packet on an Ethernet is about fifteen hundred bytes. The size of a TCP/IP packet is limited to this amount when the data is sent over an Ethernet. If more data is transferred, more data packets need to be sent by the operating system.

For the layers to serve their designated functions, additional information regarding each layer must be saved in the data packet. This takes place in the header of the packet. Every layer attaches a small block of data, called the protocol header, to the front of each emerging packet. A sample TCP/IP data packet traveling over an Ethernet cable is illustrated in Figure 16.2, “TCP/IP Ethernet Packet”. The proof sum is located at the end of the packet, not at the beginning. This simplifies things for the network hardware.

TCP/IP Ethernet Packet
Figure 16.2: TCP/IP Ethernet Packet

When an application sends data over the network, the data passes through each layer, all implemented in the Linux kernel except the physical layer. Each layer is responsible for preparing the data so it can be passed to the next layer. The lowest layer is ultimately responsible for sending the data. The entire procedure is reversed when data is received. Like the layers of an onion, in each layer the protocol headers are removed from the transported data. Finally, the transport layer is responsible for making the data available for use by the applications at the destination. In this manner, one layer only communicates with the layer directly above or below it. For applications, it is irrelevant whether data is transmitted via a 100 Mbit/s FDDI network or via a 56-Kbit/s modem line. Likewise, it is irrelevant for the data line which kind of data is transmitted, as long as packets are in the correct format.

16.1 IP Addresses and Routing

The discussion in this section is limited to IPv4 networks. For information about IPv6 protocol, the successor to IPv4, refer to Section 16.2, “IPv6—The Next Generation Internet”.

16.1.1 IP Addresses

Every computer on the Internet has a unique 32-bit address. These 32 bits (or 4 bytes) are normally written as illustrated in the second row in Example 16.1, “Writing IP Addresses”.

Example 16.1: Writing IP Addresses
IP Address (binary):  11000000 10101000 00000000 00010100
IP Address (decimal):      192.     168.       0.      20

In decimal form, the four bytes are written in the decimal number system, separated by periods. The IP address is assigned to a host or a network interface. It can be used only once throughout the world. There are exceptions to this rule, but these are not relevant to the following passages.

The points in IP addresses indicate the hierarchical system. Until the 1990s, IP addresses were strictly categorized in classes. However, this system proved too inflexible and was discontinued. Now, classless routing (CIDR, classless interdomain routing) is used.

16.1.2 Netmasks and Routing

Netmasks are used to define the address range of a subnet. If two hosts are in the same subnet, they can reach each other directly. If they are not in the same subnet, they need the address of a gateway that handles all the traffic for the subnet. To check if two IP addresses are in the same subnet, simply AND both addresses with the netmask. If the result is identical, both IP addresses are in the same local network. If there are differences, the remote IP address, and thus the remote interface, can only be reached over a gateway.

To understand how the netmask works, look at Example 16.2, “Linking IP Addresses to the Netmask”. The netmask consists of 32 bits that identify how much of an IP address belongs to the network. All those bits that are 1 mark the corresponding bit in the IP address as belonging to the network. All bits that are 0 mark bits inside the subnet. This means that the more bits are 1, the smaller the subnet is. Because the netmask always consists of several successive 1 bits, it is also possible to count the number of bits in the netmask. In Example 16.2, “Linking IP Addresses to the Netmask” the first net with 24 bits could also be written as 192.168.0.0/24.

Example 16.2: Linking IP Addresses to the Netmask
IP address (192.168.0.20):  11000000 10101000 00000000 00010100
Netmask   (255.255.255.0):  11111111 11111111 11111111 00000000
---------------------------------------------------------------
Result of the link:         11000000 10101000 00000000 00000000
In the decimal system:           192.     168.       0.       0

IP address (213.95.15.200): 11010101 10111111 00001111 11001000
Netmask    (255.255.255.0): 11111111 11111111 11111111 00000000
---------------------------------------------------------------
Result of the link:         11010101 10111111 00001111 00000000
In the decimal system:           213.      95.      15.       0

To give another example: all machines connected with the same Ethernet cable are usually located in the same subnet and are directly accessible. Even when the subnet is physically divided by switches or bridges, these hosts can still be reached directly.

IP addresses outside the local subnet can only be reached if a gateway is configured for the target network. In the most common case, there is only one gateway that handles all traffic that is external. However, it is also possible to configure several gateways for different subnets.

If a gateway has been configured, all external IP packets are sent to the appropriate gateway. This gateway then attempts to forward the packets in the same manner—from host to host—until it reaches the destination host or the packet's TTL (time to live) expires.

Specific Addresses
Base Network Address

This is the netmask AND any address in the network, as shown in Example 16.2, “Linking IP Addresses to the Netmask” under Result. This address cannot be assigned to any hosts.

Broadcast Address

This could be paraphrased as: Access all hosts in this subnet. To generate this, the netmask is inverted in binary form and linked to the base network address with a logical OR. The above example therefore results in 192.168.0.255. This address cannot be assigned to any hosts.

Local Host

The address 127.0.0.1 is assigned to the loopback device on each host. A connection can be set up to your own machine with this address and with all addresses from the complete 127.0.0.0/8 loopback network as defined with IPv4. With IPv6 there is only one loopback address (::1).

Because IP addresses must be unique all over the world, you cannot select random addresses. There are three address domains to use if you want to set up a private IP-based network. These cannot get any connection from the rest of the Internet, because they cannot be transmitted over the Internet. These address domains are specified in RFC 1597 and listed in Table 16.1, “Private IP Address Domains”.

Table 16.1: Private IP Address Domains

Network/Netmask

Domain

10.0.0.0/255.0.0.0

10.x.x.x

172.16.0.0/255.240.0.0

172.16.x.x172.31.x.x

192.168.0.0/255.255.0.0

192.168.x.x

16.2 IPv6—The Next Generation Internet

Important
Important: IBM z Systems: IPv6 Support

IPv6 is not supported by the CTC and IUCV network connections of the IBM z Systems hardware.

Due to the emergence of the World Wide Web (WWW), the Internet has experienced explosive growth, with an increasing number of computers communicating via TCP/IP in the past fifteen years. Since Tim Berners-Lee at CERN (http://public.web.cern.ch) invented the WWW in 1990, the number of Internet hosts has grown from a few thousand to about a hundred million.

As mentioned, an IPv4 address consists of only 32 bits. Also, quite a few IP addresses are lost—they cannot be used because of the way in which networks are organized. The number of addresses available in your subnet is two to the power of the number of bits, minus two. A subnet has, for example, 2, 6, or 14 addresses available. To connect 128 hosts to the Internet, for example, you need a subnet with 256 IP addresses, from which only 254 are usable, because two IP addresses are needed for the structure of the subnet itself: the broadcast and the base network address.

Under the current IPv4 protocol, DHCP or NAT (network address translation) are the typical mechanisms used to circumvent the potential address shortage. Combined with the convention to keep private and public address spaces separate, these methods can certainly mitigate the shortage. The problem with them lies in their configuration, which is a chore to set up and a burden to maintain. To set up a host in an IPv4 network, you need several address items, such as the host's own IP address, the subnetmask, the gateway address and maybe a name server address. All these items need to be known and cannot be derived from somewhere else.

With IPv6, both the address shortage and the complicated configuration should be a thing of the past. The following sections tell more about the improvements and benefits brought by IPv6 and about the transition from the old protocol to the new one.

16.2.1 Advantages

The most important and most visible improvement brought by the new protocol is the enormous expansion of the available address space. An IPv6 address is made up of 128 bit values instead of the traditional 32 bits. This provides for as many as several quadrillion IP addresses.

However, IPv6 addresses are not only different from their predecessors with regard to their length. They also have a different internal structure that may contain more specific information about the systems and the networks to which they belong. More details about this are found in Section 16.2.2, “Address Types and Structure”.

The following is a list of other advantages of the new protocol:

Autoconfiguration

IPv6 makes the network plug and play capable, which means that a newly set up system integrates into the (local) network without any manual configuration. The new host uses its automatic configuration mechanism to derive its own address from the information made available by the neighboring routers, relying on a protocol called the neighbor discovery (ND) protocol. This method does not require any intervention on the administrator's part and there is no need to maintain a central server for address allocation—an additional advantage over IPv4, where automatic address allocation requires a DHCP server.

Nevertheless if a router is connected to a switch, the router should send periodic advertisements with flags telling the hosts of a network how they should interact with each other. For more information, see RFC 2462 and the radvd.conf(5) man page, and RFC 3315.

Mobility

IPv6 makes it possible to assign several addresses to one network interface at the same time. This allows users to access several networks easily, something that could be compared with the international roaming services offered by mobile phone companies. When you take your mobile phone abroad, the phone automatically logs in to a foreign service when it enters the corresponding area, so you can be reached under the same number everywhere and can place an outgoing call, as you would in your home area.

Secure Communication

With IPv4, network security is an add-on function. IPv6 includes IPsec as one of its core features, allowing systems to communicate over a secure tunnel to avoid eavesdropping by outsiders on the Internet.

Backward Compatibility

Realistically, it would be impossible to switch the entire Internet from IPv4 to IPv6 at one time. Therefore, it is crucial that both protocols can coexist not only on the Internet, but also on one system. This is ensured by compatible addresses (IPv4 addresses can easily be translated into IPv6 addresses) and by using several tunnels. See Section 16.2.3, “Coexistence of IPv4 and IPv6”. Also, systems can rely on a dual stack IP technique to support both protocols at the same time, meaning that they have two network stacks that are completely separate, such that there is no interference between the two protocol versions.

Custom Tailored Services through Multicasting

With IPv4, some services, such as SMB, need to broadcast their packets to all hosts in the local network. IPv6 allows a much more fine-grained approach by enabling servers to address hosts through multicasting, that is by addressing several hosts as parts of a group. This is different from addressing all hosts through broadcasting or each host individually through unicasting). Which hosts are addressed as a group may depend on the concrete application. There are some predefined groups to address all name servers (the all name servers multicast group), for example, or all routers (the all routers multicast group).

16.2.2 Address Types and Structure

As mentioned, the current IP protocol has two major limitations: there is an increasing shortage of IP addresses, and configuring the network and maintaining the routing tables is becoming a more complex and burdensome task. IPv6 solves the first problem by expanding the address space to 128 bits. The second one is mitigated by introducing a hierarchical address structure combined with sophisticated techniques to allocate network addresses, and multihoming (the ability to assign several addresses to one device, giving access to several networks).

When dealing with IPv6, it is useful to know about three different types of addresses:

Unicast

Addresses of this type are associated with exactly one network interface. Packets with such an address are delivered to only one destination. Accordingly, unicast addresses are used to transfer packets to individual hosts on the local network or the Internet.

Multicast

Addresses of this type relate to a group of network interfaces. Packets with such an address are delivered to all destinations that belong to the group. Multicast addresses are mainly used by certain network services to communicate with certain groups of hosts in a well-directed manner.

Anycast

Addresses of this type are related to a group of interfaces. Packets with such an address are delivered to the member of the group that is closest to the sender, according to the principles of the underlying routing protocol. Anycast addresses are used to make it easier for hosts to find out about servers offering certain services in the given network area. All servers of the same type have the same anycast address. Whenever a host requests a service, it receives a reply from the server with the closest location, as determined by the routing protocol. If this server should fail for some reason, the protocol automatically selects the second closest server, then the third one, and so forth.

An IPv6 address is made up of eight four-digit fields, each representing 16 bits, written in hexadecimal notation. They are separated by colons (:). Any leading zero bytes within a given field may be dropped, but zeros within the field or at its end may not. Another convention is that more than four consecutive zero bytes may be collapsed into a double colon. However, only one such :: is allowed per address. This kind of shorthand notation is shown in Example 16.3, “Sample IPv6 Address”, where all three lines represent the same address.

Example 16.3: Sample IPv6 Address
fe80 : 0000 : 0000 : 0000 : 0000 : 10 : 1000 : 1a4
fe80 :    0 :    0 :    0 :    0 : 10 : 1000 : 1a4
fe80 :                           : 10 : 1000 : 1a4

Each part of an IPv6 address has a defined function. The first bytes form the prefix and specify the type of address. The center part is the network portion of the address, but it may be unused. The end of the address forms the host part. With IPv6, the netmask is defined by indicating the length of the prefix after a slash at the end of the address. An address, as shown in Example 16.4, “IPv6 Address Specifying the Prefix Length”, contains the information that the first 64 bits form the network part of the address and the last 64 form its host part. In other words, the 64 means that the netmask is filled with 64 1-bit values from the left. As with IPv4, the IP address is combined with AND with the values from the netmask to determine whether the host is located in the same subnet or in another one.

Example 16.4: IPv6 Address Specifying the Prefix Length
fe80::10:1000:1a4/64

IPv6 knows about several predefined types of prefixes. Some are shown in Various IPv6 Prefixes.

Various IPv6 Prefixes
00

IPv4 addresses and IPv4 over IPv6 compatibility addresses. These are used to maintain compatibility with IPv4. Their use still requires a router able to translate IPv6 packets into IPv4 packets. Several special addresses, such as the one for the loopback device, have this prefix as well.

2 or 3 as the first digit

Aggregatable global unicast addresses. As is the case with IPv4, an interface can be assigned to form part of a certain subnet. Currently, there are the following address spaces: 2001::/16 (production quality address space) and 2002::/16 (6to4 address space).

fe80::/10

Link-local addresses. Addresses with this prefix should not be routed and should therefore only be reachable from within the same subnet.

fec0::/10

Site-local addresses. These may be routed, but only within the network of the organization to which they belong. In effect, they are the IPv6 equivalent of the current private network address space, such as 10.x.x.x.

ff

These are multicast addresses.

A unicast address consists of three basic components:

Public Topology

The first part (which also contains one of the prefixes mentioned above) is used to route packets through the public Internet. It includes information about the company or institution that provides the Internet access.

Site Topology

The second part contains routing information about the subnet to which to deliver the packet.

Interface ID

The third part identifies the interface to which to deliver the packet. This also allows for the MAC to form part of the address. Given that the MAC is a globally unique, fixed identifier coded into the device by the hardware maker, the configuration procedure is substantially simplified. In fact, the first 64 address bits are consolidated to form the EUI-64 token, with the last 48 bits taken from the MAC, and the remaining 24 bits containing special information about the token type. This also makes it possible to assign an EUI-64 token to interfaces that do not have a MAC, such as those based on PPP.

On top of this basic structure, IPv6 distinguishes between five different types of unicast addresses:

:: (unspecified)

This address is used by the host as its source address when the interface is initialized for the first time (at which point, the address cannot yet be determined by other means).

::1 (loopback)

The address of the loopback device.

IPv4 Compatible Addresses

The IPv6 address is formed by the IPv4 address and a prefix consisting of 96 zero bits. This type of compatibility address is used for tunneling (see Section 16.2.3, “Coexistence of IPv4 and IPv6”) to allow IPv4 and IPv6 hosts to communicate with others operating in a pure IPv4 environment.

IPv4 Addresses Mapped to IPv6

This type of address specifies a pure IPv4 address in IPv6 notation.

Local Addresses

There are two address types for local use:

link-local

This type of address can only be used in the local subnet. Packets with a source or target address of this type should not be routed to the Internet or other subnets. These addresses contain a special prefix (fe80::/10) and the interface ID of the network card, with the middle part consisting of zero bytes. Addresses of this type are used during automatic configuration to communicate with other hosts belonging to the same subnet.

site-local

Packets with this type of address may be routed to other subnets, but not to the wider Internet—they must remain inside the organization's own network. Such addresses are used for intranets and are an equivalent of the private address space defined by IPv4. They contain a special prefix (fec0::/10), the interface ID, and a 16 bit field specifying the subnet ID. Again, the rest is filled with zero bytes.

As a completely new feature introduced with IPv6, each network interface normally gets several IP addresses, with the advantage that several networks can be accessed through the same interface. One of these networks can be configured completely automatically using the MAC and a known prefix with the result that all hosts on the local network can be reached when IPv6 is enabled (using the link-local address). With the MAC forming part of it, any IP address used in the world is unique. The only variable parts of the address are those specifying the site topology and the public topology, depending on the actual network in which the host is currently operating.

For a host to go back and forth between different networks, it needs at least two addresses. One of them, the home address, not only contains the interface ID but also an identifier of the home network to which it normally belongs (and the corresponding prefix). The home address is a static address and, as such, it does not normally change. Still, all packets destined to the mobile host can be delivered to it, regardless of whether it operates in the home network or somewhere outside. This is made possible by the completely new features introduced with IPv6, such as stateless autoconfiguration and neighbor discovery. In addition to its home address, a mobile host gets one or more additional addresses that belong to the foreign networks where it is roaming. These are called care-of addresses. The home network has a facility that forwards any packets destined to the host when it is roaming outside. In an IPv6 environment, this task is performed by the home agent, which takes all packets destined to the home address and relays them through a tunnel. On the other hand, those packets destined to the care-of address are directly transferred to the mobile host without any special detours.

16.2.3 Coexistence of IPv4 and IPv6

The migration of all hosts connected to the Internet from IPv4 to IPv6 is a gradual process. Both protocols will coexist for some time to come. The coexistence on one system is guaranteed where there is a dual stack implementation of both protocols. That still leaves the question of how an IPv6 enabled host should communicate with an IPv4 host and how IPv6 packets should be transported by the current networks, which are predominantly IPv4-based. The best solutions offer tunneling and compatibility addresses (see Section 16.2.2, “Address Types and Structure”).

IPv6 hosts that are more or less isolated in the (worldwide) IPv4 network can communicate through tunnels: IPv6 packets are encapsulated as IPv4 packets to move them across an IPv4 network. Such a connection between two IPv4 hosts is called a tunnel. To achieve this, packets must include the IPv6 destination address (or the corresponding prefix) and the IPv4 address of the remote host at the receiving end of the tunnel. A basic tunnel can be configured manually according to an agreement between the hosts' administrators. This is also called static tunneling.

However, the configuration and maintenance of static tunnels is often too labor-intensive to use them for daily communication needs. Therefore, IPv6 provides for three different methods of dynamic tunneling:

6over4

IPv6 packets are automatically encapsulated as IPv4 packets and sent over an IPv4 network capable of multicasting. IPv6 is tricked into seeing the whole network (Internet) as a huge local area network (LAN). This makes it possible to determine the receiving end of the IPv4 tunnel automatically. However, this method does not scale very well and is also hampered because IP multicasting is far from widespread on the Internet. Therefore, it only provides a solution for smaller corporate or institutional networks where multicasting can be enabled. The specifications for this method are laid down in RFC 2529.

6to4

With this method, IPv4 addresses are automatically generated from IPv6 addresses, enabling isolated IPv6 hosts to communicate over an IPv4 network. However, several problems have been reported regarding the communication between those isolated IPv6 hosts and the Internet. The method is described in RFC 3056.

IPv6 Tunnel Broker

This method relies on special servers that provide dedicated tunnels for IPv6 hosts. It is described in RFC 3053.

16.2.4 Configuring IPv6

To configure IPv6, you normally do not need to make any changes on the individual workstations. IPv6 is enabled by default. To disable or enable IPv6 on an installed system, use the YaST Network Settings module. On the Global Options tab, check or uncheck the Enable IPv6 option as necessary. To enable it temporarily until the next reboot, enter modprobe -i ipv6 as root. It is impossible to unload the IPv6 module after it has been loaded.

Because of the autoconfiguration concept of IPv6, the network card is assigned an address in the link-local network. Normally, no routing table management takes place on a workstation. The network routers can be queried by the workstation, using the router advertisement protocol, for what prefix and gateways should be implemented. The radvd program can be used to set up an IPv6 router. This program informs the workstations which prefix to use for the IPv6 addresses and which routers. Alternatively, use zebra/quagga for automatic configuration of both addresses and routing.

For information about how to set up various types of tunnels using the /etc/sysconfig/network files, see the man page of ifcfg-tunnel (man ifcfg-tunnel).

16.2.5 For More Information

The above overview does not cover the topic of IPv6 comprehensively. For a more in-depth look at the new protocol, refer to the following online documentation and books:

http://www.ipv6.org/

The starting point for everything about IPv6.

http://www.ipv6day.org

All information needed to start your own IPv6 network.

http://www.ipv6-to-standard.org/

The list of IPv6-enabled products.

http://www.bieringer.de/linux/IPv6/

Here, find the Linux IPv6-HOWTO and many links related to the topic.

RFC 2460

The fundamental RFC about IPv6.

IPv6 Essentials

A book describing all the important aspects of the topic is IPv6 Essentials by Silvia Hagen (ISBN 0-596-00125-8).

16.3 Name Resolution

DNS assists in assigning an IP address to one or more names and assigning a name to an IP address. In Linux, this conversion is usually carried out by a special type of software known as bind. The machine that takes care of this conversion is called a name server. The names make up a hierarchical system in which each name component is separated by a period. The name hierarchy is, however, independent of the IP address hierarchy described above.

Consider a complete name, such as jupiter.example.com, written in the format hostname.domain. A full name, called a fully qualified domain name (FQDN), consists of a host name and a domain name (example.com). The latter also includes the top level domain or TLD (com).

TLD assignment has become quite confusing for historical reasons. Traditionally, three-letter domain names are used in the USA. In the rest of the world, the two-letter ISO national codes are the standard. In addition to that, longer TLDs were introduced in 2000 that represent certain spheres of activity (for example, .info, .name, .museum).

In the early days of the Internet (before 1990), the file /etc/hosts was used to store the names of all the machines represented over the Internet. This quickly proved to be impractical in the face of the rapidly growing number of computers connected to the Internet. For this reason, a decentralized database was developed to store the host names in a widely distributed manner. This database, similar to the name server, does not have the data pertaining to all hosts in the Internet readily available, but can dispatch requests to other name servers.

The top of the hierarchy is occupied by root name servers. These root name servers manage the top level domains and are run by the Network Information Center (NIC). Each root name server knows about the name servers responsible for a given top level domain. Information about top level domain NICs is available at http://www.internic.net.

DNS can do more than resolve host names. The name server also knows which host is receiving e-mails for an entire domain—the mail exchanger (MX).

For your machine to resolve an IP address, it must know about at least one name server and its IP address. Easily specify such a name server using YaST. The configuration of name server access with SUSE® Linux Enterprise Server is described in Section 16.4.1.4, “Configuring Host Name and DNS”. Setting up your own name server is described in Chapter 25, The Domain Name System.

The protocol whois is closely related to DNS. With this program, quickly find out who is responsible for a given domain.

Note
Note: MDNS and .local Domain Names

The .local top level domain is treated as link-local domain by the resolver. DNS requests are send as multicast DNS requests instead of normal DNS requests. If you already use the .local domain in your name server configuration, you must switch this option off in /etc/host.conf. For more information, see the host.conf manual page.

If you want to switch off MDNS during installation, use nomdns=1 as a boot parameter.

For more information on multicast DNS, see http://www.multicastdns.org.

16.4 Configuring a Network Connection with YaST

  • Filename: net_yast.xml
  • ID: sec.basicnet.yast

There are many supported networking types on Linux. Most of them use different device names and the configuration files are spread over several locations in the file system. For a detailed overview of the aspects of manual network configuration, see Section 16.5, “Configuring a Network Connection Manually”.

All network interfaces with link up (with a network cable connected) are automatically configured. Additional hardware can be configured any time on the installed system. The following sections describe the network configuration for all types of network connections supported by SUSE Linux Enterprise Server.

Tip
Tip: IBM z Systems: Hotpluggable Network Cards

On IBM z Systems platforms, hotpluggable network cards are supported, but not their automatic network integration via DHCP (as is the case on the PC). After detection, manually configure the interface.

16.4.1 Configuring the Network Card with YaST

To configure your Ethernet or Wi-Fi/Bluetooth card in YaST, select System › Network Settings. After starting the module, YaST displays the Network Settings dialog with four tabs: Global Options, Overview, Hostname/DNS and Routing.

The Global Options tab allows you to set general networking options such as the network setup method, IPv6, and general DHCP options. For more information, see Section 16.4.1.1, “Configuring Global Networking Options”.

The Overview tab contains information about installed network interfaces and configurations. Any properly detected network card is listed with its name. You can manually configure new cards, remove or change their configuration in this dialog. To manually configure a card that was not automatically detected, see Section 16.4.1.3, “Configuring an Undetected Network Card”. If you want to change the configuration of an already configured card, see Section 16.4.1.2, “Changing the Configuration of a Network Card”.

The Hostname/DNS tab allows to set the host name of the machine and name the servers to be used. For more information, see Section 16.4.1.4, “Configuring Host Name and DNS”.

The Routing tab is used for the configuration of routing. See Section 16.4.1.5, “Configuring Routing” for more information.

Configuring Network Settings
Figure 16.3: Configuring Network Settings

16.4.1.1 Configuring Global Networking Options

The Global Options tab of the YaST Network Settings module allows you to set important global networking options, such as the use of NetworkManager, IPv6 and DHCP client options. These settings are applicable for all network interfaces.

Note
Note: NetworkManager Provided by Workstation Extension

NetworkManager is now provided by the Workstation Extension. To install NetworkManager, activate the Workstation Extension repository, and select the NetworkManager packages.

In the Network Setup Method choose the way network connections are managed. If you want a NetworkManager desktop applet to manage connections for all interfaces, choose NetworkManager Service. NetworkManager is well suited for switching between multiple wired and wireless networks. If you do not run a desktop environment, or if your computer is a Xen server, virtual system, or provides network services such as DHCP or DNS in your network, use the Wicked Service method. If NetworkManager is used, nm-applet should be used to configure network options and the Overview, Hostname/DNS and Routing tabs of the Network Settings module are disabled. For more information on NetworkManager, see the SUSE Linux Enterprise Desktop documentation.

In the IPv6 Protocol Settings choose whether to use the IPv6 protocol. It is possible to use IPv6 together with IPv4. By default, IPv6 is enabled. However, in networks not using IPv6 protocol, response times can be faster with IPv6 protocol disabled. To disable IPv6, deactivate Enable IPv6. If IPv6 is disabled, the kernel no longer loads the IPv6 module automatically. This setting will be applied after reboot.

In the DHCP Client Options configure options for the DHCP client. The DHCP Client Identifier must be different for each DHCP client on a single network. If left empty, it defaults to the hardware address of the network interface. However, if you are running several virtual machines using the same network interface and, therefore, the same hardware address, specify a unique free-form identifier here.

The Hostname to Send specifies a string used for the host name option field when the DHCP client sends messages to DHCP server. Some DHCP servers update name server zones (forward and reverse records) according to this host name (Dynamic DNS). Also, some DHCP servers require the Hostname to Send option field to contain a specific string in the DHCP messages from clients. Leave AUTO to send the current host name (that is the one defined in /etc/HOSTNAME). Make the option field empty for not sending any host name.

If you do not want to change the default route according to the information from DHCP, deactivate Change Default Route via DHCP.

16.4.1.2 Changing the Configuration of a Network Card

To change the configuration of a network card, select a card from the list of the detected cards in Network Settings › Overview in YaST and click Edit. The Network Card Setup dialog appears in which to adjust the card configuration using the General, Address and Hardware tabs.

16.4.1.2.1 Configuring IP Addresses

You can set the IP address of the network card or the way its IP address is determined in the Address tab of the Network Card Setup dialog. Both IPv4 and IPv6 addresses are supported. The network card can have No IP Address (which is useful for bonding devices), a Statically Assigned IP Address (IPv4 or IPv6) or a Dynamic Address assigned via DHCP or Zeroconf or both.

If using Dynamic Address, select whether to use DHCP Version 4 Only (for IPv4), DHCP Version 6 Only (for IPv6) or DHCP Both Version 4 and 6.

If possible, the first network card with link that is available during the installation is automatically configured to use automatic address setup via DHCP.

Note
Note: IBM z Systems and DHCP

On IBM z Systems platforms, DHCP-based address configuration is only supported with network cards that have a MAC address. This is only the case with OSA and OSA Express cards.

DHCP should also be used if you are using a DSL line but with no static IP assigned by the ISP (Internet Service Provider). If you decide to use DHCP, configure the details in DHCP Client Options in the Global Options tab of the Network Settings dialog of the YaST network card configuration module. If you have a virtual host setup where different hosts communicate through the same interface, an DHCP Client Identifier is necessary to distinguish them.

DHCP is a good choice for client configuration but it is not ideal for server configuration. To set a static IP address, proceed as follows:

  1. Select a card from the list of detected cards in the Overview tab of the YaST network card configuration module and click Edit.

  2. In the Address tab, choose Statically Assigned IP Address.

  3. Enter the IP Address. Both IPv4 and IPv6 addresses can be used. Enter the network mask in Subnet Mask. If the IPv6 address is used, use Subnet Mask for prefix length in format /64.

    Optionally, you can enter a fully qualified Hostname for this address, which will be written to the /etc/hosts configuration file.

  4. Click Next.

  5. To activate the configuration, click OK.

Note
Note: Interface Activation and Link Detection

During activation of a network interface, wicked checks for a carrier and only applies the IP configuration when a link has been detected. If you need to apply the configuration regardless of the link status (for example, when you want to test a service listening to a certain address), you can skip link detection by adding the variable LINK_REQUIRED=no to the configuration file of the interface in /etc/sysconfig/network/ifcfg.

Additionally, you can use the variable LINK_READY_WAIT=5 to specify the timeout for waiting for a link in seconds.

For more information about the ifcfg-* configuration files, refer to Section 16.5.2.5, “/etc/sysconfig/network/ifcfg-* and man 5 ifcfg.

If you use the static address, the name servers and default gateway are not configured automatically. To configure name servers, proceed as described in Section 16.4.1.4, “Configuring Host Name and DNS”. To configure a gateway, proceed as described in Section 16.4.1.5, “Configuring Routing”.

16.4.1.2.2 Configuring Multiple Addresses

One network device can have multiple IP addresses.

Note
Note: Aliases Are a Compatibility Feature

These so-called aliases or labels, respectively, work with IPv4 only. With IPv6 they will be ignored. Using iproute2 network interfaces can have one or more addresses.

Using YaST to set additional addresses for your network card, proceed as follows:

  1. Select a card from the list of detected cards in the Overview tab of the YaST Network Settings dialog and click Edit.

  2. In the Address › Additional Addresses tab, click Add.

  3. Enter IPv4 Address Label, IP Address, and Netmask. Do not include the interface name in the alias name.

  4. To activate the configuration, confirm the settings.

16.4.1.2.3 Changing the Device Name and Udev Rules

It is possible to change the device name of the network card when it is used. It is also possible to determine whether the network card should be identified by udev via its hardware (MAC) address or via the bus ID. The later option is preferable in large servers to simplify hotplugging of cards. To set these options with YaST, proceed as follows:

  1. Select a card from the list of detected cards in the Overview tab of the YaST Network Settings dialog and click Edit.

  2. Go to the Hardware tab. The current device name is shown in Udev Rules. Click Change.

  3. Select whether udev should identify the card by its MAC Address or Bus ID. The current MAC address and bus ID of the card are shown in the dialog.

  4. To change the device name, check the Change Device Name option and edit the name.

  5. To activate the configuration, confirm the settings.

16.4.1.2.4 Changing Network Card Kernel Driver

For some network cards, several kernel drivers may be available. If the card is already configured, YaST allows you to select a kernel driver to be used from a list of available suitable drivers. It is also possible to specify options for the kernel driver. To set these options with YaST, proceed as follows:

  1. Select a card from the list of detected cards in the Overview tab of the YaST Network Settings module and click Edit.

  2. Go to the Hardware tab.

  3. Select the kernel driver to be used in Module Name. Enter any options for the selected driver in Options in the form = =VALUE. If more options are used, they should be space-separated.

  4. To activate the configuration, confirm the settings.

16.4.1.2.5 Activating the Network Device

If you use the method with wicked, you can configure your device to either start during boot, on cable connection, on card detection, manually, or never. To change device start-up, proceed as follows:

  1. In YaST select a card from the list of detected cards in System › Network Settings and click Edit.

  2. In the General tab, select the desired entry from Device Activation.

    Choose At Boot Time to start the device during the system boot. With On Cable Connection, the interface is watched for any existing physical connection. With On Hotplug, the interface is set when available. It is similar to the At Boot Time option, and only differs in that no error occurs if the interface is not present at boot time. Choose Manually to control the interface manually with ifup. Choose Never to not start the device. The On NFSroot is similar to At Boot Time, but the interface does not shut down with the systemctl stop network command; the network service also cares about the wicked service if wicked is active. Use this if you use an NFS or iSCSI root file system.

  3. To activate the configuration, confirm the settings.

Tip
Tip: NFS as a Root File System

On (diskless) systems where the root partition is mounted via network as an NFS share, you need to be careful when configuring the network device with which the NFS share is accessible.

When shutting down or rebooting the system, the default processing order is to turn off network connections, then unmount the root partition. With NFS root, this order causes problems as the root partition cannot be cleanly unmounted as the network connection to the NFS share is already not activated. To prevent the system from deactivating the relevant network device, open the network device configuration tab as described in Section 16.4.1.2.5, “Activating the Network Device” and choose On NFSroot in the Device Activation pane.

16.4.1.2.6 Setting Up Maximum Transfer Unit Size

You can set a maximum transmission unit (MTU) for the interface. MTU refers to the largest allowed packet size in bytes. A higher MTU brings higher bandwidth efficiency. However, large packets can block up a slow interface for some time, increasing the lag for further packets.

  1. In YaST select a card from the list of detected cards in System › Network Settings and click Edit.

  2. In the General tab, select the desired entry from the Set MTU list.

  3. To activate the configuration, confirm the settings.

16.4.1.2.7 PCIe Multifunction Devices

Multifunction devices that support LAN, iSCSI, and FCoE are supported. YaST FCoE client (yast2 fcoe-client) shows the private flags in additional columns to allow the user to select the device meant for FCoE. YaST network module (yast2 lan) excludes storage only devices for network configuration.

For more information about FCoE, see Section 15.3, “Managing FCoE Services with YaST”.

16.4.1.2.8 Infiniband Configuration for IP-over-InfiniBand (IPoIB)
  1. In YaST select the InfiniBand device in System › Network Settings and click Edit.

  2. In the General tab, select one of the IP-over-InfiniBand (IPoIB) modes: connected (default) or datagram.

  3. To activate the configuration, confirm the settings.

For more information about InfiniBand, see /usr/src/linux/Documentation/infiniband/ipoib.txt.

16.4.1.2.9 Configuring the Firewall

Without having to enter the detailed firewall setup as described in Section 15.4.1, “Configuring the Firewall with YaST”, you can determine the basic firewall configuration for your device as part of the device setup. Proceed as follows:

  1. Open the YaST System › Network Settings module. In the Overview tab, select a card from the list of detected cards and click Edit.

  2. Enter the General tab of the Network Settings dialog.

  3. Determine the Firewall Zone to which your interface should be assigned. The following options are available:

    Firewall Disabled

    This option is available only if the firewall is disabled and the firewall does not run. Only use this option if your machine is part of a greater network that is protected by an outer firewall.

    Automatically Assign Zone

    This option is available only if the firewall is enabled. The firewall is running and the interface is automatically assigned to a firewall zone. The zone which contains the keyword any or the external zone will be used for such an interface.

    Internal Zone (Unprotected)

    The firewall is running, but does not enforce any rules to protect this interface. Use this option if your machine is part of a greater network that is protected by an outer firewall. It is also useful for the interfaces connected to the internal network, when the machine has more network interfaces.

    Demilitarized Zone

    A demilitarized zone is an additional line of defense in front of an internal network and the (hostile) Internet. Hosts assigned to this zone can be reached from the internal network and from the Internet, but cannot access the internal network.

    External Zone

    The firewall is running on this interface and fully protects it against other—presumably hostile—network traffic. This is the default option.

  4. To activate the configuration, confirm the settings.

16.4.1.3 Configuring an Undetected Network Card

If a network card is not detected correctly, the card is not included in the list of detected cards. If you are sure that your system includes a driver for your card, you can configure it manually. You can also configure special network device types, such as bridge, bond, TUN or TAP. To configure an undetected network card (or a special device) proceed as follows:

  1. In the System › Network Settings › Overview dialog in YaST click Add.

  2. In the Hardware dialog, set the Device Type of the interface from the available options and Configuration Name. If the network card is a PCMCIA or USB device, activate the respective check box and exit this dialog with Next. Otherwise, you can define the kernel Module Name to be used for the card and its Options, if necessary.

    In Ethtool Options, you can set ethtool options used by ifup for the interface. For information about available options, see the ethtool manual page.

    If the option string starts with a - (for example, -K INTERFACE_NAME rx on), the second word in the string is replaced with the current interface name. Otherwise (for example, autoneg off speed 10) ifup adds -s INTERFACE_NAME to the beginning.

  3. Click Next.

  4. Configure any needed options, such as the IP address, device activation or firewall zone for the interface in the General, Address, and Hardware tabs. For more information about the configuration options, see Section 16.4.1.2, “Changing the Configuration of a Network Card”.

  5. If you selected Wireless as the device type of the interface, configure the wireless connection in the next dialog.

  6. To activate the new network configuration, confirm the settings.

16.4.1.4 Configuring Host Name and DNS

If you did not change the network configuration during installation and the Ethernet card was already available, a host name was automatically generated for your computer and DHCP was activated. The same applies to the name service information your host needs to integrate into a network environment. If DHCP is used for network address setup, the list of domain name servers is automatically filled with the appropriate data. If a static setup is preferred, set these values manually.

To change the name of your computer and adjust the name server search list, proceed as follows:

  1. Go to the Network Settings › Hostname/DNS tab in the System module in YaST.

  2. Enter the Hostname and, if needed, the Domain Name. The domain is especially important if the machine is a mail server. Note that the host name is global and applies to all set network interfaces.

    If you are using DHCP to get an IP address, the host name of your computer will be automatically set by the DHCP. You should disable this behavior if you connect to different networks, because they may assign different host names and changing the host name at runtime may confuse the graphical desktop. To disable using DHCP to get an IP address deactivate Change Hostname via DHCP.

    Assign Hostname to Loopback IP associates your host name with 127.0.0.2 (loopback) IP address in /etc/hosts. This is a useful option if you want to have the host name resolvable at all times, even without active network.

  3. In Modify DNS Configuration, select the way the DNS configuration (name servers, search list, the content of the /etc/resolv.conf file) is modified.

    If the Use Default Policy option is selected, the configuration is handled by the netconfig script which merges the data defined statically (with YaST or in the configuration files) with data obtained dynamically (from the DHCP client or NetworkManager). This default policy is usually sufficient.

    If the Only Manually option is selected, netconfig is not allowed to modify the /etc/resolv.conf file. However, this file can be edited manually.

    If the Custom Policy option is selected, a Custom Policy Rule string defining the merge policy should be specified. The string consists of a comma-separated list of interface names to be considered a valid source of settings. Except for complete interface names, basic wild cards to match multiple interfaces are allowed, as well. For example, eth* ppp? will first target all eth and then all ppp0-ppp9 interfaces. There are two special policy values that indicate how to apply the static settings defined in the /etc/sysconfig/network/config file:

    STATIC

    The static settings need to be merged together with the dynamic settings.

    STATIC_FALLBACK

    The static settings are used only when no dynamic configuration is available.

    For more information, see the man page of netconfig(8) (man 8 netconfig).

  4. Enter the Name Servers and fill in the Domain Search list. Name servers must be specified by IP addresses, such as 192.168.1.116, not by host names. Names specified in the Domain Search tab are domain names used for resolving host names without a specified domain. If more than one Domain Search is used, separate domains with commas or white space.

  5. To activate the configuration, confirm the settings.

It is also possible to edit the host name using YaST from the command line. The changes made by YaST take effect immediately (which is not the case when editing the /etc/HOSTNAME file manually). To change the host name, use the following command:

yast dns edit hostname=HOSTNAME

To change the name servers, use the following commands:

yast dns edit nameserver1=192.168.1.116
yast dns edit nameserver2=192.168.1.117
yast dns edit nameserver3=192.168.1.118

16.4.1.5 Configuring Routing

To make your machine communicate with other machines and other networks, routing information must be given to make network traffic take the correct path. If DHCP is used, this information is automatically provided. If a static setup is used, this data must be added manually.

  1. In YaST go to Network Settings › Routing.

  2. Enter the IP address of the Default Gateway (IPv4 and IPv6 if necessary). The default gateway matches every possible destination, but if a routing table entry exists that matches the required address, this will be used instead of the default route via the Default Gateway.

  3. More entries can be entered in the Routing Table. Enter the Destination network IP address, Gateway IP address and the Netmask. Select the Device through which the traffic to the defined network will be routed (the minus sign stands for any device). To omit any of these values, use the minus sign -. To enter a default gateway into the table, use default in the Destination field.

    Note
    Note: Route Prioritization

    If more default routes are used, it is possible to specify the metric option to determine which route has a higher priority. To specify the metric option, enter - metric NUMBER in Options. The route with the highest metric is used as default. If the network device is disconnected, its route will be removed and the next one will be used. However, the current kernel does not use metric in static routing, only routing daemons like multipathd do.

  4. If the system is a router, enable IPv4 Forwarding and IPv6 Forwarding in the Network Settings as needed.

  5. To activate the configuration, confirm the settings.

16.4.2 IBM z Systems: Configuring Network Devices

  • Filename: zseries_net_lan_devices.xml
  • ID: sec.basicnet.yast.s390

SUSE Linux Enterprise Server for IBM z Systems supports several types of network interfaces. YaST can be used to configure all of them.

16.4.2.1 The qeth-hsi Device

To add a qeth-hsi (Hipersockets) interface to the installed system, start the System › Network Settings module in YaST. Select one of the devices marked Hipersocket to use as the READ device address and click Edit. Enter the device numbers for the read, write and control channels (example device number format: 0.0.0800). Then click next. In the Network Address Setup dialog, specify the IP address and netmask for the new interface and leave the network configuration by clicking Next and OK.

16.4.2.2 The qeth-ethernet Device

To add a qeth-ethernet (IBM OSA Express Ethernet Card) interface to the installed system, start the System › Network Settings module in YaST. Select one of the devices marked IBM OSA Express Ethernet Card to use as the READ device address and click Edit. Enter a device number for the read, write and control channels (example device number format: 0.0.0700). Enter the needed port name, port number (if applicable) and some additional options (see the Linux for IBM z Systems: Device Drivers, Features, and Commands manual for reference, http://www.ibm.com/developerworks/linux/linux390/documentation_suse.html), your IP address, and an appropriate netmask. Leave the network configuration with Next and OK.

16.4.2.3 The ctc Device

To add a ctc (IBM parallel CTC Adapter) interface to the installed system, start the System › Network Settings module in YaST. Select one of the devices marked IBM Parallel CTC Adapter to use as your read channel and click Configure. Choose the Device Settings that fit your devices (usually this would be Compatibility Mode). Specify both your IP address and the IP address of the remote partner. If needed, adjust the MTU size with Advanced › Detailed Settings. Leave the network configuration with Next and OK.

Warning
Warning: CTC is no Longer Supported

The use of this interface is deprecated. This interface will not be supported in future versions of SUSE Linux Enterprise Server.

16.4.2.4 The lcs Device

To add an lcs (IBM OSA-2 Adapter) interface to the installed system, start the System › Network Settings module in YaST. Select one of the devices marked IBM OSA-2 Adapter and click Configure. Enter the needed port number, some additional options (see the Linux for IBM z Systems: Device Drivers, Features, and Commands manual for reference, http://www.ibm.com/developerworks/linux/linux390/documentation_suse.html), your IP address and an appropriate netmask. Leave the network configuration with Next and OK.

16.4.2.5 The IUCV Device

To add an iucv (IUCV) interface to the installed system, start the System › Network Settings module in YaST. Select a device marked IUCV and click Edit. YaST prompts you for the name of your IUCV partner (Peer). Enter the name (this entry is case-sensitive) and select Next. Specify both the IP Address and the Remote IP Address of your partner. If needed, Set MTU size on General tab. Leave the network configuration with Next and OK.

Warning
Warning: IUCV is no Longer Supported

The use of this interface is deprecated. This interface will not be supported in future versions of SUSE Linux Enterprise Server.

16.5 Configuring a Network Connection Manually

  • Filename: net_wicked.xml
  • ID: sec.basicnet.manconf

Manual configuration of the network software should be the last alternative. Using YaST is recommended. However, this background information about the network configuration can also assist your work with YaST.

16.5.1 The wicked Network Configuration

The tool and library called wicked provides a new framework for network configuration.

One of the challenges with traditional network interface management is that different layers of network management get jumbled together into one single script, or at most two different scripts. These scripts interact with each other in a way that is not well-defined. This leads to unpredictable issues, obscure constraints and conventions, etc. Several layers of special hacks for a variety of different scenarios increase the maintenance burden. Address configuration protocols are being used that are implemented via daemons like dhcpcd, which interact rather poorly with the rest of the infrastructure. Funky interface naming schemes that require heavy udev support are introduced to achieve persistent identification of interfaces.

The idea of wicked is to decompose the problem in several ways. None of them is entirely novel, but trying to put ideas from different projects together is hopefully going to create a better solution overall.

One approach is to use a client/server model. This allows wicked to define standardized facilities for things like address configuration that are well integrated with the overall framework. For example, using a specific address configuration, the administrator may request that an interface should be configured via DHCP or IPv4 zeroconf. In this case, the address configuration service simply obtains the lease from its server and passes it on to the wicked server process that installs the requested addresses and routes.

The other approach to decomposing the problem is to enforce the layering aspect. For any type of network interface, it is possible to define a dbus service that configures the network interface's device layer—a VLAN, a bridge, a bonding, or a paravirtualized device. Common functionality, such as address configuration, is implemented by joint services that are layered on top of these device specific services without having to implement them specifically.

The wicked framework implements these two aspects by using a variety of dbus services, which get attached to a network interface depending on its type. Here is a rough overview of the current object hierarchy in wicked.

Each network interface is represented via a child object of /org/opensuse/Network/Interfaces. The name of the child object is given by its ifindex. For example, the loopback interface, which usually gets ifindex 1, is /org/opensuse/Network/Interfaces/1, the first Ethernet interface registered is /org/opensuse/Network/Interfaces/2.

Each network interface has a class associated with it, which is used to select the dbus interfaces it supports. By default, each network interface is of class netif, and wickedd will automatically attach all interfaces compatible with this class. In the current implementation, this includes the following interfaces:

org.opensuse.Network.Interface

Generic network interface functions, such as taking the link up or down, assigning an MTU, etc.

org.opensuse.Network.Addrconf.ipv4.dhcp, org.opensuse.Network.Addrconf.ipv6.dhcp, org.opensuse.Network.Addrconf.ipv4.auto

Address configuration services for DHCP, IPv4 zeroconf, etc.

Beyond this, network interfaces may require or offer special configuration mechanisms. For an Ethernet device, for example, you should be able to control the link speed, offloading of checksumming, etc. To achieve this, Ethernet devices have a class of their own, called netif-ethernet, which is a subclass of netif. As a consequence, the dbus interfaces assigned to an Ethernet interface include all the services listed above, plus the org.opensuse.Network.Ethernet service available only to objects belonging to the netif-ethernet class.

Similarly, there exist classes for interface types like bridges, VLANs, bonds, or infinibands.

How do you interact with an interface like VLAN (which is really a virtual network interface that sits on top of an Ethernet device) that needs to be created first? For this, wicked defines factory interfaces, such as org.opensuse.Network.VLAN.Factory. Such a factory interface offers a single function that lets you create an interface of the requested type. These factory interfaces are attached to the /org/opensuse/Network/Interfaces list node.

16.5.1.1 wicked Architecture and Features

The wicked service comprises several parts as depicted in Figure 16.4, “wicked architecture”.

wicked architecture
Figure 16.4: wicked architecture

wicked currently supports the following:

  • Configuration file back-ends to parse SUSE style /etc/sysconfig/network files.

  • An internal configuration back-end to represent network interface configuration in XML.

  • Bring up and shutdown of normal network interfaces such as Ethernet or InfiniBand, VLAN, bridge, bonds, tun, tap, dummy, macvlan, macvtap, hsi, qeth, iucv, and wireless (currently limited to one wpa-psk/eap network) devices.

  • A built-in DHCPv4 client and a built-in DHCPv6 client.

  • The nanny daemon (enabled by default) helps to automatically bring up configured interfaces when the device is available (interface hotplugging) and set up the IP configuration when a link (carrier) is detected. See Section 16.5.1.3, “Nanny” for more information.

  • wicked was implemented as a group of DBus services that are integrated with systemd. So the usual systemctl commands will apply to wicked.

16.5.1.2 Using wicked

On SUSE Linux Enterprise, wicked is running by default. If you want to check what is currently enabled and whether it is running, call:

On openSUSE Leap wicked is running by default on desktop or server hardware. On mobile hardware NetworkManager is running by default. If you want to check what is currently enabled and whether it is running, call:

systemctl status network

If wicked is enabled, you will see something along these lines:

wicked.service - wicked managed network interfaces
    Loaded: loaded (/usr/lib/systemd/system/wicked.service; enabled)
    ...

In case something different is running (for example, NetworkManager) and you want to switch to wicked, first stop what is running and then enable wicked:

systemctl is-active network && \
systemctl stop      network
systemctl enable --force wicked

This enables the wicked services, creates the network.service to wicked.service alias link, and starts the network at the next boot.

Starting the server process:

systemctl start wickedd

This starts wickedd (the main server) and associated supplicants:

/usr/lib/wicked/bin/wickedd-auto4 --systemd --foreground
/usr/lib/wicked/bin/wickedd-dhcp4 --systemd --foreground
/usr/lib/wicked/bin/wickedd-dhcp6 --systemd --foreground
/usr/sbin/wickedd --systemd --foreground
/usr/sbin/wickedd-nanny --systemd --foreground

Then bringing up the network:

systemctl start wicked

Alternatively use the network.service alias:

systemctl start network

These commands are using the default or system configuration sources as defined in /etc/wicked/client.xml.

To enable debugging, set WICKED_DEBUG in /etc/sysconfig/network/config, for example:

WICKED_DEBUG="all"

Or, to omit some:

WICKED_DEBUG="all,-dbus,-objectmodel,-xpath,-xml"

Use the client utility to display interface information for all interfaces or the interface specified with IFNAME:

wicked show all
wicked show IFNAME

In XML output:

wicked show-xml all
wicked show-xml IFNAME

Bringing up one interface:

wicked ifup eth0
wicked ifup wlan0
...

Because there is no configuration source specified, the wicked client checks its default sources of configuration defined in /etc/wicked/client.xml:

  1. firmware: iSCSI Boot Firmware Table (iBFT)

  2. compat: ifcfg files—implemented for compatibility

Whatever wicked gets from those sources for a given interface is applied. The intended order of importance is firmware, then compat—this may be changed in the future.

For more information, see the wicked man page.

16.5.1.3 Nanny

Nanny is an event and policy driven daemon that is responsible for asynchronous or unsolicited scenarios such as hotplugging devices. Thus the nanny daemon helps with starting or restarting delayed or temporarily gone devices. Nanny monitors device and link changes, and integrates new devices defined by the current policy set. Nanny continues to set up even if ifup already exited because of specified timeout constraints.

By default, the nanny daemon is active on the system. It is enabled in the /etc/wicked/common.xml configuration file:

<config>
  ...
  <use-nanny>true</use-nanny>
</config>

This setting causes ifup and ifreload to apply a policy with the effective configuration to the nanny daemon; then, nanny configures wickedd and thus ensures hotplug support. It waits in the background for events or changes (such as new devices or carrier on).

16.5.1.4 Bringing Up Multiple Interfaces

For bonds and bridges, it may make sense to define the entire device topology in one file (ifcfg-bondX), and bring it up in one go. wicked then can bring up the whole configuration if you specify the top level interface names (of the bridge or bond):

wicked ifup br0

This command automatically sets up the bridge and its dependencies in the appropriate order without the need to list the dependencies (ports, etc.) separately.

To bring up multiple interfaces in one command:

wicked ifup bond0 br0 br1 br2

Or also all interfaces:

wicked ifup all

16.5.1.5 Using Tunnels with Wicked

When you need to use tunnels with Wicked, the TUNNEL_DEVICE is used for this. It permits to specify an optional device name to bind the tunnel to the device. The tunneled packets will only be routed via this device.

For more information, refer to man 5 ifcfg-tunnel.

16.5.1.6 Handling Incremental Changes

With wicked, there is no need to actually take down an interface to reconfigure it (unless it is required by the kernel). For example, to add another IP address or route to a statically configured network interface, add the IP address to the interface definition, and do another ifup operation. The server will try hard to update only those settings that have changed. This applies to link-level options such as the device MTU or the MAC address, and network-level settings, such as addresses, routes, or even the address configuration mode (for example, when moving from a static configuration to DHCP).

Things get tricky of course with virtual interfaces combining several real devices such as bridges or bonds. For bonded devices, it is not possible to change certain parameters while the device is up. Doing that will result in an error.

However, what should still work, is the act of adding or removing the child devices of a bond or bridge, or choosing a bond's primary interface.

16.5.1.7 Wicked Extensions: Address Configuration

wicked is designed to be extensible with shell scripts. These extensions can be defined in the config.xml file.

Currently, several classes of extensions are supported:

  • link configuration: these are scripts responsible for setting up a device's link layer according to the configuration provided by the client, and for tearing it down again.

  • address configuration: these are scripts responsible for managing a device's address configuration. Usually address configuration and DHCP are managed by wicked itself, but can be implemented by means of extensions.

  • firewall extension: these scripts can apply firewall rules.

Typically, extensions have a start and a stop command, an optional pid file, and a set of environment variables that get passed to the script.

To illustrate how this is supposed to work, look at a firewall extension defined in etc/server.xml:

<dbus-service interface="org.opensuse.Network.Firewall">
 <action name="firewallUp"   command="/etc/wicked/extensions/firewall up"/>
 <action name="firewallDown" command="/etc/wicked/extensions/firewall down"/>

 <!-- default environment for all calls to this extension script -->
 <putenv name="WICKED_OBJECT_PATH" value="$object-path"/>
 <putenv name="WICKED_INTERFACE_NAME" value="$property:name"/>
 <putenv name="WICKED_INTERFACE_INDEX" value="$property:index"/>
</dbus-service>

The extension is attached to the <dbus-service> tag and defines commands to execute for the actions of this interface. Further, the declaration can define and initialize environment variables passed to the actions.

16.5.1.8 Wicked Extensions: Configuration Files

You can extend the handling of configuration files with scripts as well. For example, DNS updates from leases are ultimately handled by the extensions/resolver script, with behavior configured in server.xml:

<system-updater name="resolver">
 <action name="backup" command="/etc/wicked/extensions/resolver backup"/>
 <action name="restore" command="/etc/wicked/extensions/resolver restore"/>
 <action name="install" command="/etc/wicked/extensions/resolver install"/>
 <action name="remove" command="/etc/wicked/extensions/resolver remove"/>
</system-updater>

When an update arrives in wickedd, the system updater routines parse the lease and call the appropriate commands (backup, install, etc.) in the resolver script. This in turn configures the DNS settings using /sbin/netconfig, or by manually writing /etc/resolv.conf as a fallback.

16.5.2 Configuration Files

  • Filename: net_config_files.xml
  • ID: sec.basicnet.manconf.files

This section provides an overview of the network configuration files and explains their purpose and the format used.

16.5.2.1 /etc/wicked/common.xml

The /etc/wicked/common.xml file contains common definitions that should be used by all applications. It is sourced/included by the other configuration files in this directory. Although you can use this file to enable debugging across all wicked components, we recommend to use the file /etc/wicked/local.xml for this purpose. After applying maintenance updates you might lose your changes as the /etc/wicked/common.xml might be overwritten. The /etc/wicked/common.xml file includes the /etc/wicked/local.xml in the default installation, thus you typically do not need to modify the /etc/wicked/common.xml.

In case you want to disable nanny by setting the <use-nanny> to false, restart the wickedd.service and then run the following command to apply all configurations and policies:

wicked ifup all
Note
Note: Configuration Files

The wickedd, wicked, or nanny programs try to read /etc/wicked/common.xml if their own configuration files do not exist.

16.5.2.2 /etc/wicked/server.xml

The file /etc/wicked/server.xml is read by the wickedd server process at start-up. The file stores extensions to the /etc/wicked/common.xml. On top of that this file configures handling of a resolver and receiving information from addrconf supplicants, for example DHCP.

We recommend to add changes required to this file into a separate file /etc/wicked/server-local.xml, that gets included by /etc/wicked/server.xml. By using a separate file you avoid overwriting of your changes during maintenance updates.

16.5.2.3 /etc/wicked/client.xml

The /etc/wicked/client.xml is used by the wicked command. The file specifies the location of a script used when discovering devices managed by ibft and configures locations of network interface configurations.

We recommend to add changes required to this file into a separate file /etc/wicked/client-local.xml, that gets included by /etc/wicked/server.xml. By using a separate file you avoid overwriting of your changes during maintenance updates.

16.5.2.4 /etc/wicked/nanny.xml

The /etc/wicked/nanny.xml configures types of link layers. We recommend to add specific configuration into a separate file: /etc/wicked/nanny-local.xml to avoid losing the changes during maintenance updates.

16.5.2.5 /etc/sysconfig/network/ifcfg-*

These files contain the traditional configurations for network interfaces. In SUSE Linux Enterprise 11, this was the only supported format besides iBFT firmware.

Note
Note: wicked and the ifcfg-* Files

wicked reads these files if you specify the compat: prefix. According to the SUSE Linux Enterprise Server default configuration in /etc/wicked/client.xml, wicked tries these files before the XML configuration files in /etc/wicked/ifconfig.

The --ifconfig switch is provided mostly for testing only. If specified, default configuration sources defined in /etc/wicked/ifconfig are not applied.

The ifcfg-* files include information such as the start mode and the IP address. Possible parameters are described in the manual page of ifup. Additionally, most variables from the dhcp and wireless files can be used in the ifcfg-* files if a general setting should be used for only one interface. However, most of the /etc/sysconfig/network/config variables are global and cannot be overridden in ifcfg-files. For example, NETCONFIG_* variables are global.

For configuring macvlan and macvtab interfaces, see the ifcfg-macvlan and ifcfg-macvtap man pages. For example, for a macvlan interface provide a ifcfg-macvlan0 with settings as follows:

STARTMODE='auto'
MACVLAN_DEVICE='eth0'
#MACVLAN_MODE='vepa'
#LLADDR=02:03:04:05:06:aa

For ifcfg.template, see Section 16.5.2.6, “/etc/sysconfig/network/config, /etc/sysconfig/network/dhcp, and /etc/sysconfig/network/wireless.

System z IBM z Systems does not support USB. The names of the interface files and network aliases contain z Systems-specific elements like qeth.

16.5.2.6 /etc/sysconfig/network/config, /etc/sysconfig/network/dhcp, and /etc/sysconfig/network/wireless

The file config contains general settings for the behavior of ifup, ifdown and ifstatus. dhcp contains settings for DHCP and wireless for wireless LAN cards. The variables in all three configuration files are commented. Some variables from /etc/sysconfig/network/config can also be used in ifcfg-* files, where they are given a higher priority. The /etc/sysconfig/network/ifcfg.template file lists variables that can be specified in a per interface scope. However, most of the /etc/sysconfig/network/config variables are global and cannot be overridden in ifcfg-files. For example, NETWORKMANAGER or NETCONFIG_* variables are global.

Note
Note: Using DHCPv6

In SUSE Linux Enterprise 11, DHCPv6 used to work even on networks where IPv6 Router Advertisements (RAs) were not configured properly. Starting with SUSE Linux Enterprise 12, DHCPv6 will correctly require that at least one of the routers on the network sends out RAs that indicate that this network is managed by DHCPv6.

For networks where the router cannot be configured correctly, the ifcfg option allows the user to override this behavior by specifying DHCLIENT6_MODE='managed' in the ifcfg file. You can also activate this workaround with a boot parameter in the installation system:

ifcfg=eth0=dhcp6,DHCLIENT6_MODE=managed

16.5.2.7 /etc/sysconfig/network/routes and /etc/sysconfig/network/ifroute-*

The static routing of TCP/IP packets is determined by the /etc/sysconfig/network/routes and /etc/sysconfig/network/ifroute-* files. All the static routes required by the various system tasks can be specified in /etc/sysconfig/network/routes: routes to a host, routes to a host via a gateway and routes to a network. For each interface that needs individual routing, define an additional configuration file: /etc/sysconfig/network/ifroute-*. Replace the wild card (*) with the name of the interface. The entries in the routing configuration files look like this:

# Destination     Gateway           Netmask            Interface  Options

The route's destination is in the first column. This column may contain the IP address of a network or host or, in the case of reachable name servers, the fully qualified network or host name. The network should be written in CIDR notation (address with the associated routing prefix-length) such as 10.10.0.0/16 for IPv4 or fc00::/7 for IPv6 routes. The keyword default indicates that the route is the default gateway in the same address family as the gateway. For devices without a gateway use explicit 0.0.0.0/0 or ::/0 destinations.

The second column contains the default gateway or a gateway through which a host or network can be accessed.

The third column is deprecated; it used to contain the IPv4 netmask of the destination. For IPv6 routes, the default route, or when using a prefix-length (CIDR notation) in the first column, enter a dash (-) here.

The fourth column contains the name of the interface. If you leave it empty using a dash (-), it can cause unintended behavior in /etc/sysconfig/network/routes. For more information, see the routes man page.

An (optional) fifth column can be used to specify special options. For details, see the routes man page.

Example 16.5: Common Network Interfaces and Some Static Routes
# --- IPv4 routes in CIDR prefix notation:
# Destination     [Gateway]         -                  Interface
127.0.0.0/8       -                 -                  lo
204.127.235.0/24  -                 -                  eth0
default           204.127.235.41    -                  eth0
207.68.156.51/32  207.68.145.45     -                  eth1
192.168.0.0/16    207.68.156.51     -                  eth1

# --- IPv4 routes in deprecated netmask notation"
# Destination     [Dummy/Gateway]   Netmask            Interface
#
127.0.0.0         0.0.0.0           255.255.255.0      lo
204.127.235.0     0.0.0.0           255.255.255.0      eth0
default           204.127.235.41    0.0.0.0            eth0
207.68.156.51     207.68.145.45     255.255.255.255    eth1
192.168.0.0       207.68.156.51     255.255.0.0        eth1

# --- IPv6 routes are always using CIDR notation:
# Destination     [Gateway]                -           Interface
2001:DB8:100::/64 -                        -           eth0
2001:DB8:100::/32 fe80::216:3eff:fe6d:c042 -           eth0

16.5.2.8 /etc/resolv.conf

The domain to which the host belongs is specified in /etc/resolv.conf (keyword search). Up to six domains with a total of 256 characters can be specified with the search option. When resolving a name that is not fully qualified, an attempt is made to generate one by attaching the individual search entries. Up to 3 name servers can be specified with the nameserver option, each on a line of its own. Comments are preceded by hash mark or semicolon signs (# or ;). As an example, see Example 16.6, “/etc/resolv.conf.

However, the /etc/resolv.conf should not be edited by hand. Instead, it is generated by the netconfig script. To define static DNS configuration without using YaST, edit the appropriate variables manually in the /etc/sysconfig/network/config file:

NETCONFIG_DNS_STATIC_SEARCHLIST

list of DNS domain names used for host name lookup

NETCONFIG_DNS_STATIC_SERVERS

list of name server IP addresses to use for host name lookup

NETCONFIG_DNS_FORWARDER

the name of the DNS forwarder that needs to be configured, for example bind or resolver

NETCONFIG_DNS_RESOLVER_OPTIONS

arbitrary options that will be written to /etc/resolv.conf, for example:

debug attempts:1 timeout:10

For more information, see the resolv.conf man page.

NETCONFIG_DNS_RESOLVER_SORTLIST

list of up to 10 items, for example:

130.155.160.0/255.255.240.0 130.155.0.0

For more information, see the resolv.conf man page.

To disable DNS configuration using netconfig, set NETCONFIG_DNS_POLICY=''. For more information about netconfig, see the netconfig(8) man page (man 8 netconfig).

Example 16.6: /etc/resolv.conf
# Our domain
search example.com
#
# We use dns.example.com (192.168.1.116) as nameserver
nameserver 192.168.1.116

16.5.2.9 /sbin/netconfig

netconfig is a modular tool to manage additional network configuration settings. It merges statically defined settings with settings provided by autoconfiguration mechanisms as DHCP or PPP according to a predefined policy. The required changes are applied to the system by calling the netconfig modules that are responsible for modifying a configuration file and restarting a service or a similar action.

netconfig recognizes three main actions. The netconfig modify and netconfig remove commands are used by daemons such as DHCP or PPP to provide or remove settings to netconfig. Only the netconfig update command is available for the user:

modify

The netconfig modify command modifies the current interface and service specific dynamic settings and updates the network configuration. Netconfig reads settings from standard input or from a file specified with the --lease-file FILENAME option and internally stores them until a system reboot (or the next modify or remove action). Already existing settings for the same interface and service combination are overwritten. The interface is specified by the -i INTERFACE_NAME parameter. The service is specified by the -s SERVICE_NAME parameter.

remove

The netconfig remove command removes the dynamic settings provided by a modificatory action for the specified interface and service combination and updates the network configuration. The interface is specified by the -i INTERFACE_NAME parameter. The service is specified by the -s SERVICE_NAME parameter.

update

The netconfig update command updates the network configuration using current settings. This is useful when the policy or the static configuration has changed. Use the -m MODULE_TYPE parameter, if you want to update a specified service only (dns, nis, or ntp).

The netconfig policy and the static configuration settings are defined either manually or using YaST in the /etc/sysconfig/network/config file. The dynamic configuration settings provided by autoconfiguration tools such as DHCP or PPP are delivered directly by these tools with the netconfig modify and netconfig remove actions. When NetworkManager is enabled, netconfig (in policy mode auto) uses only NetworkManager settings, ignoring settings from any other interfaces configured using the traditional ifup method. If NetworkManager does not provide any setting, static settings are used as a fallback. A mixed usage of NetworkManager and the wicked method is not supported.

For more information about netconfig, see man 8 netconfig.

16.5.2.10 /etc/hosts

In this file, shown in Example 16.7, “/etc/hosts, IP addresses are assigned to host names. If no name server is implemented, all hosts to which an IP connection will be set up must be listed here. For each host, enter a line consisting of the IP address, the fully qualified host name, and the host name into the file. The IP address must be at the beginning of the line and the entries separated by blanks and tabs. Comments are always preceded by the # sign.

Example 16.7: /etc/hosts
127.0.0.1 localhost
192.168.2.100 jupiter.example.com jupiter
192.168.2.101 venus.example.com venus

16.5.2.11 /etc/networks

Here, network names are converted to network addresses. The format is similar to that of the hosts file, except the network names precede the addresses. See Example 16.8, “/etc/networks.

Example 16.8: /etc/networks
loopback     127.0.0.0
localnet     192.168.0.0

16.5.2.12 /etc/host.conf

Name resolution—the translation of host and network names via the resolver library—is controlled by this file. This file is only used for programs linked to libc4 or libc5. For current glibc programs, refer to the settings in /etc/nsswitch.conf. Each parameter must always be entered on a separate line. Comments are preceded by a # sign. Table 16.2, “Parameters for /etc/host.conf” shows the parameters available. A sample /etc/host.conf is shown in Example 16.9, “/etc/host.conf.

Table 16.2: Parameters for /etc/host.conf

order hosts, bind

Specifies in which order the services are accessed for the name resolution. Available arguments are (separated by blank spaces or commas):

hosts: searches the /etc/hosts file

bind: accesses a name server

nis: uses NIS

multi on/off

Defines if a host entered in /etc/hosts can have multiple IP addresses.

nospoof on spoofalert on/off

These parameters influence the name server spoofing but do not exert any influence on the network configuration.

trim domainname

The specified domain name is separated from the host name after host name resolution (as long as the host name includes the domain name). This option is useful only if names from the local domain are in the /etc/hosts file, but should still be recognized with the attached domain names.

Example 16.9: /etc/host.conf
# We have named running
order hosts bind
# Allow multiple address
multi on

16.5.2.13 /etc/nsswitch.conf

The introduction of the GNU C Library 2.0 was accompanied by the introduction of the Name Service Switch (NSS). Refer to the nsswitch.conf(5) man page and The GNU C Library Reference Manual for details.

The order for queries is defined in the file /etc/nsswitch.conf. A sample nsswitch.conf is shown in Example 16.10, “/etc/nsswitch.conf. Comments are preceded by # signs. In this example, the entry under the hosts database means that a request is sent to /etc/hosts (files) via DNS (see Chapter 25, The Domain Name System).

Example 16.10: /etc/nsswitch.conf
passwd:     compat
group:      compat

hosts:      files dns
networks:   files dns

services:   db files
protocols:  db files
rpc:        files
ethers:     files
netmasks:   files
netgroup:   files nis
publickey:  files

bootparams: files
automount:  files nis
aliases:    files nis
shadow:     compat

The databases available over NSS are listed in Table 16.3, “Databases Available via /etc/nsswitch.conf”. The configuration options for NSS databases are listed in Table 16.4, “Configuration Options for NSS Databases.

Table 16.3: Databases Available via /etc/nsswitch.conf

aliases

Mail aliases implemented by sendmail; see man 5 aliases.

ethers

Ethernet addresses.

netmasks

List of networks and their subnet masks. Only needed, if you use subnetting.

group

User groups used by getgrent. See also the man page for group.

hosts

Host names and IP addresses, used by gethostbyname and similar functions.

netgroup

Valid host and user lists in the network for controlling access permissions; see the netgroup(5) man page.

networks

Network names and addresses, used by getnetent.

publickey

Public and secret keys for Secure_RPC used by NFS and NIS+.

passwd

User passwords, used by getpwent; see the passwd(5) man page.

protocols

Network protocols, used by getprotoent; see the protocols(5) man page.

rpc

Remote procedure call names and addresses, used by getrpcbyname and similar functions.

services

Network services, used by getservent.

shadow

Shadow passwords of users, used by getspnam; see the shadow(5) man page.

Table 16.4: Configuration Options for NSS Databases

files

directly access files, for example, /etc/aliases

db

access via a database

nis, nisplus

NIS, see also Chapter 3, Using NIS

dns

can only be used as an extension for hosts and networks

compat

can only be used as an extension for passwd, shadow and group

16.5.2.14 /etc/nscd.conf

This file is used to configure nscd (name service cache daemon). See the nscd(8) and nscd.conf(5) man pages. By default, the system entries of passwd, groups and hostsare cached by nscd. This is important for the performance of directory services, like NIS and LDAP, because otherwise the network connection needs to be used for every access to names, groups or hosts.

If the caching for passwd is activated, it usually takes about fifteen seconds until a newly added local user is recognized. Reduce this waiting time by restarting nscd with:

systemctl restart nscd

16.5.2.15 /etc/HOSTNAME

/etc/HOSTNAME contains the fully qualified host name (FQHN). The fully qualified host name is the host name with the domain name attached. This file must contain only one line (in which the host name is set). It is read while the machine is booting.

16.5.3 Testing the Configuration

Before you write your configuration to the configuration files, you can test it. To set up a test configuration, use the ip command. To test the connection, use the ping command.

The command ip changes the network configuration directly without saving it in the configuration file. Unless you enter your configuration in the correct configuration files, the changed network configuration is lost on reboot.

Note
Note: ifconfig and route Are Obsolete

The ifconfig and route tools are obsolete. Use ip instead. ifconfig, for example, limits interface names to 9 characters.

16.5.3.1 Configuring a Network Interface with ip

ip is a tool to show and configure network devices, routing, policy routing, and tunnels.

ip is a very complex tool. Its common syntax is ip OPTIONS OBJECT COMMAND. You can work with the following objects:

link

This object represents a network device.

address

This object represents the IP address of device.

neighbor

This object represents an ARP or NDISC cache entry.

route

This object represents the routing table entry.

rule

This object represents a rule in the routing policy database.

maddress

This object represents a multicast address.

mroute

This object represents a multicast routing cache entry.

tunnel

This object represents a tunnel over IP.

If no command is given, the default command is used (usually list).

Change the state of a device with the command ip link set DEVICE_NAME  . For example, to deactivate device eth0, enter ip link set eth0 down. To activate it again, use ip link set eth0 up.

After activating a device, you can configure it. To set the IP address, use ip addr add IP_ADDRESS + dev DEVICE_NAME. For example, to set the address of the interface eth0 to 192.168.12.154/30 with standard broadcast (option brd), enter ip addr add 192.168.12.154/30 brd + dev eth0.

To have a working connection, you must also configure the default gateway. To set a gateway for your system, enter ip route add gateway_ip_address. To translate one IP address to another, use nat: ip route add nat ip_address via other_ip_address.

To display all devices, use ip link ls. To display the running interfaces only, use ip link ls up. To print interface statistics for a device, enter ip -s link ls device_name. To view addresses of your devices, enter ip addr. In the output of the ip addr, also find information about MAC addresses of your devices. To show all routes, use ip route show.

For more information about using ip, enter ip help or see the ip(8) man page. The help option is also available for all ip subcommands. If, for example, you need help for ip addr, enter ip addr help. Find the ip manual in /usr/share/doc/packages/iproute2/ip-cref.pdf.

16.5.3.2 Testing a Connection with ping

The ping command is the standard tool for testing whether a TCP/IP connection works. It uses the ICMP protocol to send a small data packet, ECHO_REQUEST datagram, to the destination host, requesting an immediate reply. If this works, ping displays a message to that effect. This indicates that the network link is functioning.

ping does more than only test the function of the connection between two computers: it also provides some basic information about the quality of the connection. In Example 16.11, “Output of the Command ping”, you can see an example of the ping output. The second-to-last line contains information about the number of transmitted packets, packet loss, and total time of ping running.

As the destination, you can use a host name or IP address, for example, ping example.com or ping 192.168.3.100. The program sends packets until you press CtrlC.

If you only need to check the functionality of the connection, you can limit the number of the packets with the -c option. For example to limit ping to three packets, enter ping -c 3 example.com.

Example 16.11: Output of the Command ping
ping -c 3 example.com
PING example.com (192.168.3.100) 56(84) bytes of data.
64 bytes from example.com (192.168.3.100): icmp_seq=1 ttl=49 time=188 ms
64 bytes from example.com (192.168.3.100): icmp_seq=2 ttl=49 time=184 ms
64 bytes from example.com (192.168.3.100): icmp_seq=3 ttl=49 time=183 ms
--- example.com ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2007ms
rtt min/avg/max/mdev = 183.417/185.447/188.259/2.052 ms

The default interval between two packets is one second. To change the interval, ping provides the option -i. For example, to increase the ping interval to ten seconds, enter ping -i 10 example.com.

In a system with multiple network devices, it is sometimes useful to send the ping through a specific interface address. To do so, use the -I option with the name of the selected device, for example, ping -I wlan1 example.com.

For more options and information about using ping, enter ping -h or see the ping (8) man page.

Tip
Tip: Pinging IPv6 Addresses

For IPv6 addresses use the ping6 command. Note, to ping link-local addresses, you must specify the interface with -I. The following command works, if the address is reachable via eth1:

ping6 -I eth1 fe80::117:21ff:feda:a425

16.5.4 Unit Files and Start-Up Scripts

Apart from the configuration files described above, there are also systemd unit files and various scripts that load the network services while the machine is booting. These are started when the system is switched to the multi-user.target target. Some of these unit files and scripts are described in Some Unit Files and Start-Up Scripts for Network Programs. For more information about systemd, see Chapter 13, The systemd Daemon and for more information about the systemd targets, see the man page of systemd.special (man systemd.special).

Some Unit Files and Start-Up Scripts for Network Programs
network.target

network.target is the systemd target for networking, but its mean depends on the settings provided by the system administrator.

For more information, see http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget/.

multi-user.target

multi-user.target is the systemd target for a multiuser system with all required network services.

xinetd

Starts xinetd. xinetd can be used to make server services available on the system. For example, it can start vsftpd whenever an FTP connection is initiated.

rpcbind

Starts the rpcbind utility that converts RPC program numbers to universal addresses. It is needed for RPC services, such as an NFS server.

ypserv

Starts the NIS server.

ypbind

Starts the NIS client.

/etc/init.d/nfsserver

Starts the NFS server.

/etc/init.d/postfix

Controls the postfix process.

16.6 Basic Router Setup

  • Filename: net_router.xml
  • ID: sec.basicnet.router

A router is a networking device that delivers and receives data (network packets) to or from more than one network back and forth. You often use a router to connect your local network to the remote network (Internet) or to connect local network segments. With SUSE Linux Enterprise Server you can build a router with features such as NAT (Network Address Translation) or advanced firewalling.

The following are basic steps to turn SUSE Linux Enterprise Server into a router.

  1. Enable forwarding, for example in /etc/sysctl.d/50-router.conf

    net.ipv4.conf.all.forwarding = 1
    net.ipv6.conf.all.forwarding = 1

    Then provide a static IPv4 and IPv6 IP setup for the interfaces. Enabling forwarding disables several mechanisms, for example IPv6 does not accept an IPv6 RA (router advertisement) anymore, which also prevents the creation of a default route.

  2. In many situations (for example, when you can reach the same network via more than one interface, or when VPN usually is used and already on normal multi-home hosts), you must disable the IPv4 reverse path filter (this feature does not currently exist for IPv6):

    net.ipv4.conf.all.rp_filter = 0

    You can also filter with firewall settings instead.

  3. To accept an IPv6 RA (from the router on an external, uplink, or ISP interface) and create a default (or also a more specific) IPv6 route again, set:

    net.ipv6.conf.${ifname}.accept_ra = 2
    net.ipv6.conf.${ifname}.autoconf = 0

    (Note: eth0.42 needs to be written as eth0/42 in a dot-separated sysfs path.)

More router behavior and forwarding dependencies are described in https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt.

To provide IPv6 on your internal (DMZ) interfaces, and announce yourself as an IPv6 router and autoconf networks to the clients, install and configure radvd in /etc/radvd.conf, for example:

interface eth0
{
    IgnoreIfMissing on;         # do not fail if interface missed

    AdvSendAdvert on;           # enable sending RAs
    AdvManagedFlag on;          # IPv6 addresses managed via DHCPv6
    AdvOtherConfigFlag on;      # DNS, NTP... only via DHCPv6

    AdvDefaultLifetime 3600;    # client default route lifetime of 1 hour

    prefix 2001:db8:0:1::/64    # (/64 is default and required for autoconf)
    {
        AdvAutonomous off;         # Disable address autoconf (DHCPv6 only)

        AdvValidLifetime 3600;     # prefix (autoconf addr) is valid 1 h
        AdvPreferredLifetime 1800; # prefix (autoconf addr) is prefered 1/2 h
    }
}

Lastly configure the firewall. In SuSEfirewall2, you need to set FW_ROUTE="yes" (otherwise it will also reset forwarding sysctl again) and define the interfaces in the FW_DEV_INT, FW_DEV_EXT (and FW_DEV_DMZ) zone variables as needed, perhaps also FW_MASQUERADE="yes" and FW_MASQ_DEV.

16.7 Setting Up Bonding Devices

  • Filename: net_bonding.xml
  • ID: sec.bond

For some systems, there is a desire to implement network connections that comply to more than the standard data security or availability requirements of a typical Ethernet device. In these cases, several Ethernet devices can be aggregated to a single bonding device.

The configuration of the bonding device is done by means of bonding module options. The behavior is mainly affected by the mode of the bonding device. By default, this is mode=active-backup which means that a different slave device will become active if the active slave fails.

Tip
Tip: Bonding and Xen

Using bonding devices is only of interest for machines where you have multiple real network cards available. In most configurations, this means that you should use the bonding configuration only in Dom0. Only if you have multiple network cards assigned to a VM Guest system it may also be useful to set up the bond in a VM Guest.

To configure a bonding device, use the following procedure:

  1. Run YaST › System › Network Settings.

  2. Use Add and change the Device Type to Bond. Proceed with Next.

  3. Select how to assign the IP address to the bonding device. Three methods are at your disposal:

    • No IP Address

    • Dynamic Address (with DHCP or Zeroconf)

    • Statically assigned IP Address

    Use the method that is appropriate for your environment.

  4. In the Bond Slaves tab, select the Ethernet devices that should be included into the bond by activating the related check box.

  5. Edit the Bond Driver Options. The modes that are available for configuration are the following:

    • balance-rr

    • active-backup

    • balance-xor

    • broadcast

    • 802.3ad

      802.3ad is the standardized LACP IEEE 802.3ad Dynamic link aggregation mode.

    • balance-tlb

    • balance-alb

  6. Make sure that the parameter miimon=100 is added to the Bond Driver Options. Without this parameter, the data integrity is not checked regularly.

  7. Click Next and leave YaST with OK to create the device.

All modes, and many more options are explained in detail in the Linux Ethernet Bonding Driver HOWTO found at /usr/src/linux/Documentation/networking/bonding.txt after installing the package kernel-source.

16.7.1 Hotplugging of Bonding Slaves

In specific network environments (such as High Availability), there are cases when you need to replace a bonding slave interface with another one. The reason may be a constantly failing network device. The solution is to set up hotplugging of bonding slaves.

The bond is configured as usual (according to man 5 ifcfg-bonding), for example:

ifcfg-bond0
          STARTMODE='auto' # or 'onboot'
          BOOTPROTO='static'
          IPADDR='192.168.0.1/24'
          BONDING_MASTER='yes'
          BONDING_SLAVE_0='eth0'
          BONDING_SLAVE_1='eth1'
          BONDING_MODULE_OPTS='mode=active-backup miimon=100'

The slaves are specified with STARTMODE=hotplug and BOOTPROTO=none:

ifcfg-eth0
          STARTMODE='hotplug'
          BOOTPROTO='none'

ifcfg-eth1
          STARTMODE='hotplug'
          BOOTPROTO='none'

BOOTPROTO=none uses the ethtool options (when provided), but does not set the link up on ifup eth0. The reason is that the slave interface is controlled by the bond master.

STARTMODE=hotplug causes the slave interface to join the bond automatically when it is available.

The udev rules in /etc/udev/rules.d/70-persistent-net.rules need to be changed to match the device by bus ID (udev KERNELS keyword equal to "SysFS BusID" as visible in hwinfo --netcard) instead of by MAC address. This allows replacement of defective hardware (a network card in the same slot but with a different MAC) and prevents confusion when the bond changes the MAC address of all its slaves.

For example:

SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*",
KERNELS=="0000:00:19.0", ATTR{dev_id}=="0x0", ATTR{type}=="1",
KERNEL=="eth*", NAME="eth0"

At boot time, the systemd network.service does not wait for the hotplug slaves, but for the bond to become ready, which requires at least one available slave. When one of the slave interfaces gets removed (unbind from NIC driver, rmmod of the NIC driver or true PCI hotplug remove) from the system, the kernel removes it from the bond automatically. When a new card is added to the system (replacement of the hardware in the slot), udev renames it using the bus-based persistent name rule to the name of the slave, and calls ifup for it. The ifup call automatically joins it into the bond.

16.8 Setting Up Team Devices for Network Teaming

  • Filename: net_teaming.xml
  • ID: sec.team

The term link aggregation is the general term which describes combining (or aggregating) a network connection to provide a logical layer. Sometimes you find the terms channel teaming, Ethernet bonding, port truncating, etc. which are synonyms and refer to the same concept.

This concept is widely known as bonding and was originally integrated into the Linux kernel (see Section 16.7, “Setting Up Bonding Devices” for the original implementation). The term Network Teaming is used to refer to the new implementation of this concept.

The main difference between bonding and Network Teaming is that teaming supplies a set of small kernel modules responsible for providing an interface for teamd instances. Everything else is handled in user space. This is different from the original bonding implementation which contains all of its functionality exclusively in the kernel. For a comparison refer to Table 16.5, “Feature Comparison between Bonding and Team”.

Table 16.5: Feature Comparison between Bonding and Team
FeatureBondingTeam
broadcast, round-robin TX policyyesyes
active-backup TX policyyesyes
LACP (802.3ad) supportyesyes
hash-based TX policyyesyes
user can set hash functionnoyes
TX load-balancing support (TLB)yesyes
TX load-balancing support for LACPnoyes
Ethtool link monitoringyesyes
ARP link monitoringyesyes
NS/NA (IPV6) link monitoringnoyes
RCU locking on TX/RX pathsnoyes
port prio and stickinessnoyes
separate per-port link monitoring setupnoyes
multiple link monitoring setuplimitedyes
VLAN supportyesyes
multiple device stackingyesyes

Source: http://libteam.org/files/teamdev.pp.pdf

Both implementations, bonding and Network Teaming, can be used in parallel. Network Teaming is an alternative to the existing bonding implementation. It does not replace bonding.

Network Teaming can be used for different use cases. The two most important use cases are explained later and involve:

  • Load balancing between different network devices.

  • Failover from one network device to another in case one of the devices should fail.

Currently, there is no YaST module to support creating a teaming device. You need to configure Network Teaming manually. The general procedure is shown below which can be applied for all your Network Teaming configurations:

Procedure 16.1: General Procedure
  1. Make sure you have all the necessary packages installed. Install the packages libteam-tools, libteamdctl0, and python-libteam.

  2. Create a configuration file under /etc/sysconfig/network/. Usually it will be ifcfg-team0. If you need more than one Network Teaming device, give them ascending numbers.

    This configuration file contains several variables which are explained in the man pages (see man ifcfg and man ifcfg-team). An example configuration can be found in your system in the file /etc/sysconfig/network/ifcfg.template.

  3. Remove the configuration files of the interfaces which will be used for the teaming device (usually ifcfg-eth0 and ifcfg-eth1).

    It is recommended to make a backup and remove both files. Wicked will re-create the configuration files with the necessary parameters for teaming.

  4. Optionally, check if everything is included in Wicked's configuration file:

    wicked show-config
  5. Start the Network Teaming device team0:

    wicked ifup all team0

    In case you need additional debug information, use the option --debug all after the all subcommand.

  6. Check the status of the Network Teaming device. This can be done by the following commands:

    • Get the state of the teamd instance from Wicked:

      wicked ifstatus --verbose team0
    • Get the state of the entire instance:

      teamdctl team0 state
    • Get the systemd state of the teamd instance:

      systemctl status teamd@team0

    Each of them shows a slightly different view depending on your needs.

  7. In case you need to change something in the ifcfg-team0 file afterward, reload its configuration with:

    wicked ifreload team0

Do not use systemctl for starting or stopping the teaming device! Instead, use the wicked command as shown above.

To completely remove the team device, use this procedure:

Procedure 16.2: Removing a Team Device
  1. Stop the Network Teaming device team0:

    wicked ifdown team0
  2. Rename the file /etc/sysconfig/network/ifcfg-team0 to /etc/sysconfig/network/.ifcfg-team0. Inserting a dot in front of the file name makes it invisible for wicked. If you really do not need the configuration anymore, you can also remove the file.

  3. Reload the configuration:

    wicked ifreload all

16.8.1 Use Case: Loadbalancing with Network Teaming

Loadbalancing is used to improve bandwidth. Use the following configuration file to create a Network Teaming device with loadbalancing capabilities. Proceed with Procedure 16.1, “General Procedure” to set up the device. Check the output with teamdctl.

Example 16.12: Configuration for Loadbalancing with Network Teaming
STARTMODE=auto 1
BOOTPROTO=static 2
IPADDRESS="192.168.1.1/24" 2
IPADDR6="fd00:deca:fbad:50::1/64" 2

TEAM_RUNNER="loadbalance" 3
TEAM_LB_TX_HASH="ipv4,ipv6,eth,vlan"
TEAM_LB_TX_BALANCER_NAME="basic"
TEAM_LB_TX_BALANCER_INTERVAL="100"

TEAM_PORT_DEVICE_0="eth0" 4
TEAM_PORT_DEVICE_1="eth1" 4

TEAM_LW_NAME="ethtool" 5
TEAM_LW_ETHTOOL_DELAY_UP="10" 6
TEAM_LW_ETHTOOL_DELAY_DOWN="10" 6

1

Controls the start of the teaming device. The value of auto means, the interface will be set up when the network service is available and will be started automatically on every reboot.

In case you need to control the device yourself (and prevent it from starting automatically), set STARTMODE to manual.

2

Sets a static IP address (here 192.168.1.1 for IPv4 and fd00:deca:fbad:50::1 for IPv6).

If the Network Teaming device should use a dynamic IP address, set BOOTPROTO="dhcp" and remove (or comment) the line with IPADDRESS and IPADDR6.

3

Sets TEAM_RUNNER to loadbalance to activate the loadbalancing mode.

4

Specifies one or more devices which should be aggregated to create the Network Teaming device.

5

Defines a link watcher to monitor the state of subordinate devices. The default value ethtool checks only if the device is up and accessible. This makes this check fast enough. However, it does not check if the device can really send or receive packets.

If you need a higher confidence in the connection, use the arp_ping option. This sends pings to an arbitrary host (configured in the TEAM_LW_ARP_PING_TARGET_HOST variable). Only if the replies are received, the Network Teaming device is considered to be up.

6

Defines the delay in milliseconds between the link coming up (or down) and the runner being notified.

16.8.2 Use Case: Failover with Network Teaming

Failover is used to ensure high availability of a critical Network Teaming device by involving a parallel backup network device. The backup network device is running all the time and takes over if and when the main device fails.

Use the following configuration file to create a Network Teaming device with failover capabilities. Proceed with Procedure 16.1, “General Procedure” to set up the device. Check the output with teamdctl.

Example 16.13: Configuration for DHCP Network Teaming Device
STARTMODE=auto 1
BOOTPROTO=static 2
IPADDR="192.168.1.2/24" 2
IPADDR6="fd00:deca:fbad:50::2/64" 2

TEAM_RUNNER=activebackup 3
TEAM_PORT_DEVICE_0="eth0" 4
TEAM_PORT_DEVICE_1="eth1" 4

TEAM_LW_NAME=ethtool 5
TEAM_LW_ETHTOOL_DELAY_UP="10" 6
TEAM_LW_ETHTOOL_DELAY_DOWN="10" 6

1

Controls the start of the teaming device. The value of auto means, the interface will be set up when the network service is available and will be started automatically on every reboot.

In case you need to control the device yourself (and prevent it from starting automatically), set STARTMODE to manual.

2

Sets a static IP address (here 192.168.1.2 for IPv4 and fd00:deca:fbad:50::2 for IPv6).

If the Network Teaming device should use a dynamic IP address, set BOOTPROTO="dhcp" and remove (or comment) the line with IPADDRESS and IPADDR6.

3

Sets TEAM_RUNNER to activebackup to activate the failover mode.

4

Specifies one or more devices which should be aggregated to create the Network Teaming device.

5

Defines a link watcher to monitor the state of subordinate devices. The default value ethtool checks only if the device is up and accessible. This makes this check fast enough. However, it does not check if the device can really send or receive packets.

If you need a higher confidence in the connection, use the arp_ping option. This sends pings to an arbitrary host (configured in the TEAM_LW_ARP_PING_TARGET_HOST variable). Only if the replies are received, the Network Teaming device is considered to be up.

6

Defines the delay in milliseconds between the link coming up (or down) and the runner being notified.

16.8.3 Use Case: VLAN over Team Device

VLAN is an abbreviation of Virtual Local Area Network. It allows the running of multiple logical (virtual) ethernets over one single physical ethernet. It logically splits the network into different broadcast domains so that packets are only switched between ports that are designated for the same VLAN.

The following use case creates two static VLANs on top of a team device:

  • vlan0, bound to the IP address 192.168.10.1

  • vlan1, bound to the IP address 192.168.20.1

Proceed as follows:

  1. Enable the VLAN tags on your switch. If you want to use loadbalancing for your team device, your switch needs to be capable of Link Aggregation Control Protocol (LACP) (802.3ad). Consult your hardware manual about the details.

  2. Decide if you want to use loadbalancing or failover for your team device. Set up your team device as described in Section 16.8.1, “Use Case: Loadbalancing with Network Teaming” or Section 16.8.2, “Use Case: Failover with Network Teaming”.

  3. In /etc/sysconfig/network create a file ifcfg-vlan0 with the following content:

    STARTMODE="auto"
    BOOTPROTO="static" 1
    IPADDR='192.168.10.1/24' 2
    ETHERDEVICE="team0" 3
    VLAN_ID="0" 4
    VLAN='yes'

    1

    Defines a fixed IP address, specified in IPADDR.

    2

    Defines the IP address, here with its netmask.

    3

    Contains the real interface to use for the VLAN interface, here our team device (team0).

    4

    Specifies a unique ID for the VLAN. Preferably, the file name and the VLAN_ID corresponds to the name ifcfg-vlanVLAN_ID. In our case VLAN_ID is 0 which leads to the filename ifcfg-vlan0.

  4. Copy the file /etc/sysconfig/network/ifcfg-vlan0 to /etc/sysconfig/network/ifcfg-vlan1 and change the following values:

    • IPADDR from 192.168.10.1/24 to 192.168.20.1/24.

    • VLAN_ID from 0 to 1.

  5. Start the two VLANs:

    root # wicked ifup vlan0 vlan1
  6. Check the output of ifconfig:

    root # ifconfig -a
    [...]
    vlan0     Link encap:Ethernet  HWaddr 08:00:27:DC:43:98
              inet addr:192.168.10.1 Bcast:192.168.10.255 Mask:255.255.255.0
              inet6 addr: fe80::a00:27ff:fedc:4398/64 Scope:Link
              UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
              RX packets:0 errors:0 dropped:0 overruns:0 frame:0
              TX packets:12 errors:0 dropped:0 overruns:0 carrier:0
              collisions:0 txqueuelen:1000
              RX bytes:0 (0.0 b)  TX bytes:816 (816.0 b)
    
    vlan1     Link encap:Ethernet  HWaddr 08:00:27:DC:43:98
              inet addr:192.168.20.1 Bcast:192.168.20.255 Mask:255.255.255.0
              inet6 addr: fe80::a00:27ff:fedc:4398/64 Scope:Link
              UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
              RX packets:0 errors:0 dropped:0 overruns:0 frame:0
              TX packets:12 errors:0 dropped:0 overruns:0 carrier:0
              collisions:0 txqueuelen:1000
              RX bytes:0 (0.0 b)  TX bytes:816 (816.0 b)

16.9 Software-Defined Networking with Open vSwitch

  • Filename: net_sdn.xml
  • ID: sec.ovs

Software-defined networking (SDN) means separating the system that controls where traffic is sent (the control plane) from the underlying system that forwards traffic to the selected destination (the data plane, also called the forwarding plane). This means that the functions previously fulfilled by a single, usually inflexible switch, can now be separated between a switch (data plane) and its controller (control plane). In this model, the controller is programmable and can be very flexible and adapt quickly to changing network conditions.

Open vSwitch is software that implements a distributed virtual multilayer switch that is compatible with the OpenFlow protocol. OpenFlow allows a controller application to modify the configuration of a switch. OpenFlow is layered onto the TCP protocol and is implemented in a range of hardware and software. A single controller can thus drive multiple, very different switches.

16.9.1 Advantages of Open vSwitch

Software-defined networking with Open vSwitch brings several advantages with it, especially when you used together with virtual machines:

  • Networking states can be identified easily.

  • Networks and their live state can be moved from one host to another.

  • Network dynamics are traceable and external software can be enabled to respond to them.

  • You can apply and manipulate tags in network packets to identify which machine they are coming from or going to and maintain other networking context. Tagging rules can be configured and migrated.

  • Open vSwitch implements the GRE protocol (Generic Routing Encapsulation). This allows you, for example, to connect private VM networks to each other.

  • Open vSwitch can be used on its own, but is designed to integrate with networking hardware and can control hardware switches.

16.9.2 Installing Open vSwitch

  1. Install Open vSwitch and supplementary packages:

    root # zypper install openvswitch openvswitch-switch

    If you plan to use Open vSwitch together with the KVM hypervisor, additionally install tunctl . If you plan to use Open vSwitch together with the Xen hypervisor, additionally install openvswitch-kmp-xen .

  2. Enable the Open vSwitch service:

    root # systemctl enable openvswitch
  3. Either restart the computer or use systemctl to start the Open vSwitch service immediately:

    root # systemctl start openvswitch
  4. To check whether Open vSwitch was activated correctly, use:

    root # systemctl status openvswitch

16.9.3 Overview of Open vSwitch Daemons and Utilities

Open vSwitch consists of several components. Among them are a kernel module and various user space components. The kernel module is used for accelerating the data path, but is not necessary for a minimal Open vSwitch installation.

16.9.3.1 Daemons

The central executables of Open vSwitch are its two daemons. When you start the openvswitch service, you are indirectly starting them.

The main Open vSwitch daemon (ovs-vswitchd) provides the implementation of a switch. The Open vSwitch database daemon (ovsdb-server) serves the database that stores the configuration and state of Open vSwitch.

16.9.3.2 Utilities

Open vSwitch also comes with several utilities that help you work with it. The following list is not exhaustive, but instead describes important commands only.

ovsdb-tool

Create, upgrade, compact, and query Open vSwitch databases. Do transactions on Open vSwitch databases.

ovs-appctl

Configure a running ovs-vswitchd or ovsdb-server daemon.

ovs-dpctl, ovs-dpctl-top

Create, modify, visualize, and delete data paths. Using this tool can interfere with ovs-vswitchd also performing data path management. Therefore, it is often used for diagnostics only.

ovs-dpctl-top creates a top-like visualization for data paths.

ovs-ofctl

Manage any switches adhering to the OpenFlow protocol. ovs-ofctl is not limited to interacting with Open vSwitch.

ovs-vsctl

Provides a high-level interface to the configuration database. It can be used to query and modify the database. In effect, it shows the status of ovs-vswitchd and can be used to configure it.

16.9.4 Creating a Bridge with Open vSwitch

The following example configuration uses the Wicked network service that is used by default on SUSE Linux Enterprise Server. To learn more about Wicked, see Section 16.5, “Configuring a Network Connection Manually”.

When you have installed and started Open vSwitch, proceed as follows:

  1. To configure a bridge for use by your virtual machine, create a file with content like this:

    STARTMODE='auto'1
    BOOTPROTO='dhcp'2
    OVS_BRIDGE='yes'3
    OVS_BRIDGE_PORT_DEVICE_1='eth0'4

    1

    Set up the bridge automatically when the network service is started.

    2

    The protocol to use for configuring the IP address.

    3

    Mark the configuration as an Open vSwitch bridge.

    4

    Choose which device/devices should be added to the bridge. To add more devices, append additional lines for each of them to the file:

    OVS_BRIDGE_PORT_DEVICE_SUFFIX='DEVICE'

    The SUFFIX can be any alphanumeric string. However, to avoid overwriting a previous definition, make sure the SUFFIX of each device is unique.

    Save the file in the directory /etc/sysconfig/network under the name ifcfg-br0. Instead of br0, you can use any name you want. However, the file name needs to begin with ifcfg-.

    To learn about further options, refer to the man pages of ifcfg (man 5 ifcfg) and ifcfg-ovs-bridge (man 5 ifcfg-ovs-bridge).

  2. Now start the bridge:

    root # wicked ifup br0

    When Wicked is done, it should output the name of the bridge and next to it the state up.

16.9.5 Using Open vSwitch Directly with KVM

After having created the bridge as described in Section 16.9.4, “Creating a Bridge with Open vSwitch, you can use Open vSwitch to manage the network access of virtual machines created with KVM/QEMU.

  1. To be able to best use the capabilities of Wicked, make some further changes to the bridge configured before. Open the previously created /etc/sysconfig/network/ifcfg-br0 and append a line for another port device:

    OVS_BRIDGE_PORT_DEVICE_2='tap0'

    Additionally, set BOOTPROTO to none. The file should now look like this:

    STARTMODE='auto'
    BOOTPROTO='none'
    OVS_BRIDGE='yes'
    OVS_BRIDGE_PORT_DEVICE_1='eth0'
    OVS_BRIDGE_PORT_DEVICE_2='tap0'

    The new port device tap0 will be configured in the next step.

  2. Now add a configuration file for the tap0 device:

    STARTMODE='auto'
    BOOTPROTO='none'
    TUNNEL='tap'

    Save the file in the directory /etc/sysconfig/network under the name ifcfg-tap0.

    Tip
    Tip: Allowing Other Users to Access the Tap Device

    To be able to use this tap device from a virtual machine started as a user who is not root, append:

    TUNNEL_SET_OWNER=USER_NAME

    To allow access for an entire group, append:

    TUNNEL_SET_GROUP=GROUP_NAME
  3. Finally, open the configuration for the device defined as the first OVS_BRIDGE_PORT_DEVICE. If you did not change the name, that should be eth0. Therefore, open /etc/sysconfig/network/ifcfg-eth0 and make sure that the following options are set:

    STARTMODE='auto'
    BOOTPROTO='none'

    If the file does not exist yet, create it.

  4. Restart the bridge interface using Wicked:

    root # wicked ifreload br0

    This will also trigger a reload of the newly defined bridge port devices.

  5. To start a virtual machine, use, for example:

    root # qemu-kvm \
    -drive file=/PATH/TO/DISK-IMAGE1 \
    -m 512 -net nic,vlan=0,macaddr=00:11:22:EE:EE:EE \
    -net tap,ifname=tap0,script=no,downscript=no2

    1

    The path to the QEMU disk image you want to start.

    2

    Use the tap device (tap0) created before.

    For further information on the usage of KVM/QEMU, see Part V, “Managing Virtual Machines with QEMU”.

16.9.6 Using Open vSwitch with libvirt

After having created the bridge as described before in Section 16.9.4, “Creating a Bridge with Open vSwitch, you can add the bridge to an existing virtual machine managed with libvirt. Since libvirt has some support for Open vSwitch bridges already, you can use the bridge created in Section 16.9.4, “Creating a Bridge with Open vSwitch without further changes to the networking configuration.

  1. Open the domain XML file for the intended virtual machine:

    root # virsh edit VM_NAME

    Replace VM_NAME with the name of the desired virtual machine. This will open your default text editor.

  2. Find the networking section of the document by looking for a section starting with <interface type="..."> and ending in </interface>.

    Replace the existing section with a networking section that looks somewhat like this:

    <interface type='bridge'>
      <source bridge='br0'/>
      <virtualport type='openvswitch'/>
    </interface>
    Important
    Important: Compatibility of virsh iface-* and Virtual Machine Manager with Open vSwitch

    At the moment, the Open vSwitch compatibility of libvirt is not exposed through the virsh iface-* tools and Virtual Machine Manager. If you use any of these tools, your configuration can break.

  3. You can now start or restart the virtual machine as usual.

For further information on the usage of libvirt, see Part II, “Managing Virtual Machines with libvirt.

16.9.7 For More Information

http://openvswitch.org/support/

The documentation section of the Open vSwitch project Web site

https://www.opennetworking.org/images/stories/downloads/sdn-resources/white-papers/wp-sdn-newnorm.pdf

Whitepaper by the Open Networking Foundation about software-defined networking and the OpenFlow protocol

17 Printer Operation

  • Filename: printing.xml
  • ID: cha.p

SUSE® Linux Enterprise Server supports printing with many types of printers, including remote network printers. Printers can be configured manually or with YaST. For configuration instructions, refer to Section 11.3, “Setting Up a Printer”. Both graphical and command line utilities are available for starting and managing print jobs. If your printer does not work as expected, refer to Section 17.8, “Troubleshooting”.

CUPS (Common Unix Printing System) is the standard print system in SUSE Linux Enterprise Server.

Printers can be distinguished by interface, such as USB or network, and printer language. When buying a printer, make sure that the printer has an interface that is supported (USB, Ethernet, or Wi-Fi) and a suitable printer language. Printers can be categorized on the basis of the following three classes of printer languages:

PostScript Printers

PostScript is the printer language in which most print jobs in Linux and Unix are generated and processed by the internal print system. If PostScript documents can be processed directly by the printer and do not need to be converted in additional stages in the print system, the number of potential error sources is reduced.

Currently PostScript is being replaced by PDF as the standard print job format. PostScript+PDF printers that can directly print PDF (in addition to PostScript) already exist. For traditional PostScript printers PDF needs to be converted to PostScript in the printing workflow.

Standard Printers (Languages Like PCL and ESC/P)

In the case of known printer languages, the print system can convert PostScript jobs to the respective printer language with Ghostscript. This processing stage is called interpreting. The best-known languages are PCL (which is mostly used by HP printers and their clones) and ESC/P (which is used by Epson printers). These printer languages are usually supported by Linux and produce an adequate print result. Linux may not be able to address some special printer functions. Except for HP and Epson, there are currently no printer manufacturers who develop Linux drivers and make them available to Linux distributors under an open source license.

Proprietary Printers (Also Called GDI Printers)

These printers do not support any of the common printer languages. They use their own undocumented printer languages, which are subject to change when a new edition of a model is released. Usually only Windows drivers are available for these printers. See Section 17.8.1, “Printers without Standard Printer Language Support” for more information.

Before you buy a new printer, refer to the following sources to check how well the printer you intend to buy is supported:

http://www.linuxfoundation.org/OpenPrinting/

The OpenPrinting home page with the printer database. The database shows the latest Linux support status. However, a Linux distribution can only integrate the drivers available at production time. Accordingly, a printer currently rated as perfectly supported may not have had this status when the latest SUSE Linux Enterprise Server version was released. Thus, the databases may not necessarily indicate the correct status, but only provide an approximation.

http://pages.cs.wisc.edu/~ghost/

The Ghostscript Web page.

/usr/share/doc/packages/ghostscript/catalog.devices

List of built-in Ghostscript drivers.

17.1 The CUPS Workflow

The user creates a print job. The print job consists of the data to print plus information for the spooler. This includes the name of the printer or the name of the print queue, and optionally, information for the filter, such as printer-specific options.

At least one dedicated print queue exists for every printer. The spooler holds the print job in the queue until the desired printer is ready to receive data. When the printer is ready, the spooler sends the data through the filter and back-end to the printer.

The filter converts the data generated by the application that is printing (usually PostScript or PDF, but also ASCII, JPEG, etc.) into printer-specific data (PostScript, PCL, ESC/P, etc.). The features of the printer are described in the PPD files. A PPD file contains printer-specific options with the parameters needed to enable them on the printer. The filter system makes sure that options selected by the user are enabled.

If you use a PostScript printer, the filter system converts the data into printer-specific PostScript. This does not require a printer driver. If you use a non-PostScript printer, the filter system converts the data into printer-specific data. This requires a printer driver suitable for your printer. The back-end receives the printer-specific data from the filter then passes it to the printer.

17.2 Methods and Protocols for Connecting Printers

There are various possibilities for connecting a printer to the system. The configuration of CUPS does not distinguish between a local printer and a printer connected to the system over the network. For more information about the printer connection, read the article CUPS in a Nutshell at http://en.opensuse.org/SDB:CUPS_in_a_Nutshell.

System z Printers and similar devices provided by the z/VM that connect locally with the IBM z Systems mainframes are not supported by CUPS. On these platforms, printing is only possible over the network. The cabling for network printers must be installed according to the instructions of the printer manufacturer.

Warning
Warning: Changing Cable Connections in a Running System

When connecting the printer to the machine, do not forget that only USB devices can be plugged in or unplugged during operation. To avoid damaging your system or printer, shut down the system before changing any connections that are not USB.

17.3 Installing the Software

PPD (PostScript printer description) is the computer language that describes the properties, like resolution, and options, such as the availability of a duplex unit. These descriptions are required for using various printer options in CUPS. Without a PPD file, the print data would be forwarded to the printer in a raw state, which is usually not desired.

To configure a PostScript printer, the best approach is to get a suitable PPD file. Many PPD files are available in the packages manufacturer-PPDs and OpenPrintingPPDs-postscript. See Section 17.7.3, “PPD Files in Various Packages” and Section 17.8.2, “No Suitable PPD File Available for a PostScript Printer”.

New PPD files can be stored in the directory /usr/share/cups/model/ or added to the print system with YaST as described in Section 11.3.1.1, “Adding Drivers with YaST”. Subsequently, the PPD file can be selected during the printer setup.

Be careful if a printer manufacturer wants you to install entire software packages. This kind of installation may result in the loss of the support provided by SUSE Linux Enterprise Server. Also, print commands may work differently and the system may no longer be able to address devices of other manufacturers. For this reason, the installation of manufacturer software is not recommended.

17.4 Network Printers

A network printer can support various protocols, some even concurrently. Although most of the supported protocols are standardized, some manufacturers modify the standard. Manufacturers then provide drivers for only a few operating systems. Unfortunately, Linux drivers are rarely provided. The current situation is such that you cannot act on the assumption that every protocol works smoothly in Linux. Therefore, you may need to experiment with various options to achieve a functional configuration.

CUPS supports the socket, LPD, IPP and smb protocols.

socket

Socket refers to a connection in which the plain print data is sent directly to a TCP socket. Some socket port numbers that are commonly used are 9100 or 35. The device URI (uniform resource identifier) syntax is: socket://IP.OF.THE.PRINTER:PORT, for example: socket://192.168.2.202:9100/.

LPD (Line Printer Daemon)

The LPD protocol is described in RFC 1179. Under this protocol, some job-related data, such as the ID of the print queue, is sent before the actual print data is sent. Therefore, a print queue must be specified when configuring the LPD protocol. The implementations of diverse printer manufacturers are flexible enough to accept any name as the print queue. If necessary, the printer manual should indicate what name to use. LPT, LPT1, LP1 or similar names are often used. The port number for an LPD service is 515. An example device URI is lpd://192.168.2.202/LPT1.

IPP (Internet Printing Protocol)

IPP is a relatively new protocol (1999) based on the HTTP protocol. With IPP, more job-related data is transmitted than with the other protocols. CUPS uses IPP for internal data transmission. The name of the print queue is necessary to configure IPP correctly. The port number for IPP is 631. Example device URIs are ipp://192.168.2.202/ps and ipp://192.168.2.202/printers/ps.

SMB (Windows Share)

CUPS also supports printing on printers connected to Windows shares. The protocol used for this purpose is SMB. SMB uses the port numbers 137, 138 and 139. Example device URIs are smb://user:password@workgroup/smb.example.com/printer, smb://user:password@smb.example.com/printer, and smb://smb.example.com/printer.

The protocol supported by the printer must be determined before configuration. If the manufacturer does not provide the needed information, the command nmap (which comes with the nmap package) can be used to ascertain the protocol. nmap checks a host for open ports. For example:

nmap -p 35,137-139,515,631,9100-10000 IP.OF.THE.PRINTER

17.5 Configuring CUPS with Command Line Tools

CUPS can be configured with command line tools like lpinfo, lpadmin and lpoptions. You need a device URI consisting of a back-end, such as USB, and parameters. To determine valid device URIs on your system use the command lpinfo -v | grep ":/":

# lpinfo -v | grep ":/"
direct usb://ACME/FunPrinter%20XL
network socket://192.168.2.253

With lpadmin the CUPS server administrator can add, remove or manage print queues. To add a print queue, use the following syntax:

lpadmin -p QUEUE -v DEVICE-URI -P PPD-FILE -E

Then the device (-v) is available as QUEUE (-p), using the specified PPD file (-P). This means that you must know the PPD file and the device URI to configure the printer manually.

Do not use -E as the first option. For all CUPS commands, -E as the first argument sets use of an encrypted connection. To enable the printer, -E must be used as shown in the following example:

lpadmin -p ps -v usb://ACME/FunPrinter%20XL -P \
/usr/share/cups/model/Postscript.ppd.gz -E

The following example configures a network printer:

lpadmin -p ps -v socket://192.168.2.202:9100/ -P \
/usr/share/cups/model/Postscript-level1.ppd.gz -E

For more options of lpadmin, see the man page of lpadmin(8).

During printer setup, certain options are set as default. These options can be modified for every print job (depending on the print tool used). Changing these default options with YaST is also possible. Using command line tools, set default options as follows:

  1. First, list all options:

    lpoptions -p QUEUE -l

    Example:

    Resolution/Output Resolution: 150dpi *300dpi 600dpi

    The activated default option is identified by a preceding asterisk (*).

  2. Change the option with lpadmin:

    lpadmin -p QUEUE -o Resolution=600dpi
  3. Check the new setting:

    lpoptions -p QUEUE -l
    
    Resolution/Output Resolution: 150dpi 300dpi *600dpi

When a normal user runs lpoptions, the settings are written to ~/.cups/lpoptions. However, root settings are written to /etc/cups/lpoptions.

17.6 Printing from the Command Line

To print from the command line, enter lp -d QUEUENAME FILENAME, substituting the corresponding names for QUEUENAME and FILENAME.

Some applications rely on the lp command for printing. In this case, enter the correct command in the application's print dialog, usually without specifying FILENAME, for example, lp -d QUEUENAME.

17.7 Special Features in SUSE Linux Enterprise Server

Several CUPS features have been adapted for SUSE Linux Enterprise Server. Some of the most important changes are covered here.

17.7.1 CUPS and Firewall

After having performed a default installation of SUSE Linux Enterprise Server, SuSEFirewall2 is active and the network interfaces are configured to be in the External Zone which blocks incoming traffic. More information about the SuSEFirewall2 configuration is available in Section 15.4, “SuSEFirewall2” and at http://en.opensuse.org/SDB:CUPS_and_SANE_Firewall_settings.

17.7.1.1 CUPS Client

Normally, a CUPS client runs on a regular workstation located in a trusted network environment behind a firewall. In this case it is recommended to configure the network interface to be in the Internal Zone, so the workstation is reachable from within the network.

17.7.1.2 CUPS Server

If the CUPS server is part of a trusted network environment protected by a firewall, the network interface should be configured to be in the Internal Zone of the firewall. It is not recommended to set up a CUPS server in an untrusted network environment unless you ensure that it is protected by special firewall rules and secure settings in the CUPS configuration.

17.7.2 Browsing for Network Printers

CUPS servers regularly announce the availability and status information of shared printers over the network. Clients can access this information to display a list of available printers in printing dialogs, for example. This is called browsing.

CUPS servers announce their print queues over the network either via the traditional CUPS browsing protocol or via Bonjour/DND-SD. To be able to browse network print queues, the service cups-browsed needs to run on all clients that print via CUPS servers. cups-browsed is not started by default. To start it for the active session, use sudo systemctl start cups-browsed. To ensure it is automatically started after booting, enable it with sudo systemctl enable cups-browsed on all clients.

In case browsing does not work after having started cups-browsed, the CUPS server(s) probably announce the network print queues via Bonjour/DND-SD. In this case you need to additionally install the package avahi and start the associated service with sudo systemctl start avahi-daemon on all clients.

17.7.3 PPD Files in Various Packages

The YaST printer configuration sets up the queues for CUPS using the PPD files installed in /usr/share/cups/model. To find the suitable PPD files for the printer model, YaST compares the vendor and model determined during hardware detection with the vendors and models in all PPD files. For this purpose, the YaST printer configuration generates a database from the vendor and model information extracted from the PPD files.

The configuration using only PPD files and no other information sources has the advantage that the PPD files in /usr/share/cups/model can be modified freely. For example, if you have PostScript printers the PPD files can be copied directly to /usr/share/cups/model (if they do not already exist in the manufacturer-PPDs or OpenPrintingPPDs-postscript packages) to achieve an optimum configuration for your printers.

Additional PPD files are provided by the following packages:

  • gutenprint: the Gutenprint driver and its matching PPDs

  • splix: the SpliX driver and its matching PPDs

  • OpenPrintingPPDs-ghostscript: PPDs for Ghostscript built-in drivers

  • OpenPrintingPPDs-hpijs: PPDs for the HPIJS driver for non-HP printers

17.8 Troubleshooting

The following sections cover some of the most frequently encountered printer hardware and software problems and ways to solve or circumvent these problems. Among the topics covered are GDI printers, PPD files and port configuration. Common network printer problems, defective printouts, and queue handling are also addressed.

17.8.1 Printers without Standard Printer Language Support

These printers do not support any common printer language and can only be addressed with special proprietary control sequences. Therefore they can only work with the operating system versions for which the manufacturer delivers a driver. GDI is a programming interface developed by Microsoft* for graphics devices. Usually the manufacturer delivers drivers only for Windows, and since the Windows driver uses the GDI interface these printers are also called GDI printers. The actual problem is not the programming interface, but that these printers can only be addressed with the proprietary printer language of the respective printer model.

Some GDI printers can be switched to operate either in GDI mode or in one of the standard printer languages. See the manual of the printer whether this is possible. Some models require special Windows software to do the switch (note that the Windows printer driver may always switch the printer back into GDI mode when printing from Windows). For other GDI printers there are extension modules for a standard printer language available.

Some manufacturers provide proprietary drivers for their printers. The disadvantage of proprietary printer drivers is that there is no guarantee that these work with the installed print system or that they are suitable for the various hardware platforms. In contrast, printers that support a standard printer language do not depend on a special print system version or a special hardware platform.

Instead of spending time trying to make a proprietary Linux driver work, it may be more cost-effective to purchase a printer which supports a standard printer language (preferably PostScript). This would solve the driver problem once and for all, eliminating the need to install and configure special driver software and obtain driver updates that may be required because of new developments in the print system.

17.8.2 No Suitable PPD File Available for a PostScript Printer

If the manufacturer-PPDs or OpenPrintingPPDs-postscript packages do not contain a suitable PPD file for a PostScript printer, it should be possible to use the PPD file from the driver CD of the printer manufacturer or download a suitable PPD file from the Web page of the printer manufacturer.

If the PPD file is provided as a zip archive (.zip) or a self-extracting zip archive (.exe), unpack it with unzip. First, review the license terms of the PPD file. Then use the cupstestppd utility to check if the PPD file complies with Adobe PostScript Printer Description File Format Specification, version 4.3. If the utility returns FAIL, the errors in the PPD files are serious and are likely to cause major problems. The problem spots reported by cupstestppd should be eliminated. If necessary, ask the printer manufacturer for a suitable PPD file.

17.8.3 Network Printer Connections

Identifying Network Problems

Connect the printer directly to the computer. For test purposes, configure the printer as a local printer. If this works, the problems are related to the network.

Checking the TCP/IP Network

The TCP/IP network and name resolution must be functional.

Checking a Remote lpd

Use the following command to test if a TCP connection can be established to lpd (port 515) on HOST:

netcat -z HOST 515 && echo ok || echo failed

If the connection to lpd cannot be established, lpd may not be active or there may be basic network problems.

Provided that the respective lpd is active and the host accepts queries, run the following command as root to query a status report for QUEUE on remote HOST:

echo -e "\004queue" \
| netcat -w 2 -p 722 HOST 515

If lpd does not respond, it may not be active or there may be basic network problems. If lpd responds, the response should show why printing is not possible on the queue on host. If you receive a response like that shown in Example 17.1, “Error Message from lpd, the problem is caused by the remote lpd.

Example 17.1: Error Message from lpd
lpd: your host does not have line printer access
lpd: queue does not exist
printer: spooling disabled
printer: printing disabled
Checking a Remote cupsd

A CUPS network server can broadcast its queues by default every 30 seconds on UDP port 631. Accordingly, the following command can be used to test whether there is a broadcasting CUPS network server in the network. Make sure to stop your local CUPS daemon before executing the command.

netcat -u -l -p 631 & PID=$! ; sleep 40 ; kill $PID

If a broadcasting CUPS network server exists, the output appears as shown in Example 17.2, “Broadcast from the CUPS Network Server”.

Example 17.2: Broadcast from the CUPS Network Server
ipp://192.168.2.202:631/printers/queue

System z Take into account that IBM z Systems Ethernet devices do not receive broadcasts by default.

The following command can be used to test if a TCP connection can be established to cupsd (port 631) on HOST:

netcat -z HOST 631 && echo ok || echo failed

If the connection to cupsd cannot be established, cupsd may not be active or there may be basic network problems. lpstat -h HOST -l -t returns a (possibly very long) status report for all queues on HOST, provided the respective cupsd is active and the host accepts queries.

The next command can be used to test if the QUEUE on HOST accepts a print job consisting of a single carriage-return character. Nothing should be printed. Possibly, a blank page may be ejected.

echo -en "\r" \
| lp -d queue -h HOST
Troubleshooting a Network Printer or Print Server Machine

Spoolers running in a print server machine sometimes cause problems when they need to deal with multiple print jobs. Since this is caused by the spooler in the print server machine, there no way to resolve this issue. As a work-around, circumvent the spooler in the print server machine by addressing the printer connected to the print server machine directly with the TCP socket. See Section 17.4, “Network Printers”.

In this way, the print server machine is reduced to a converter between the various forms of data transfer (TCP/IP network and local printer connection). To use this method, you need to know the TCP port on the print server machine. If the printer is connected to the print server machine and turned on, this TCP port can usually be determined with the nmap utility from the nmap package some time after the print server machine is powered up. For example, nmap  IP-address may deliver the following output for a print server machine:

Port       State       Service
23/tcp     open        telnet
80/tcp     open        http
515/tcp    open        printer
631/tcp    open        cups
9100/tcp   open        jetdirect

This output indicates that the printer connected to the print server machine can be addressed via TCP socket on port 9100. By default, nmap only checks several commonly known ports listed in /usr/share/nmap/nmap-services. To check all possible ports, use the command nmap -p  FROM_PORT-TO_PORT IP_ADDRESS. This may take some time. For further information, refer to the man page of nmap.

Enter a command like

echo -en "\rHello\r\f" | netcat -w 1 IP-address port
cat file | netcat -w 1 IP-address port

to send character strings or files directly to the respective port to test if the printer can be addressed on this port.

17.8.4 Defective Printouts without Error Message

For the print system, the print job is completed when the CUPS back-end completes the data transfer to the recipient (printer). If further processing on the recipient fails (for example, if the printer is not able to print the printer-specific data) the print system does not notice this. If the printer cannot print the printer-specific data, select a PPD file that is more suitable for the printer.

17.8.5 Disabled Queues

If the data transfer to the recipient fails entirely after several attempts, the CUPS back-end, such as USB or socket, reports an error to the print system (to cupsd). The back-end determines how many unsuccessful attempts are appropriate until the data transfer is reported as impossible. As further attempts would be in vain, cupsd disables printing for the respective queue. After eliminating the cause of the problem, the system administrator must re-enable printing with the command cupsenable.

17.8.6 CUPS Browsing: Deleting Print Jobs

If a CUPS network server broadcasts its queues to the client hosts via browsing and a suitable local cupsd is active on the client hosts, the client cupsd accepts print jobs from applications and forwards them to the cupsd on the server. When cupsd on the server accepts a print job, it is assigned a new job number. Therefore, the job number on the client host is different from the job number on the server. As a print job is usually forwarded immediately, it cannot be deleted with the job number on the client host This is because the client cupsd regards the print job as completed when it has been forwarded to the server cupsd.

To delete the print job on the server, use a command such as lpstat -h cups.example.com -o to determine the job number on the server. This assumes that the server has not already completed the print job (that is, sent it completely to the printer). Use the obtained job number to delete the print job on the server as follows:

cancel -h cups.example.com QUEUE-JOBNUMBER

17.8.7 Defective Print Jobs and Data Transfer Errors

If you switch the printer off or shut down the computer during the printing process, print jobs remain in the queue. Printing resumes when the computer (or the printer) is switched back on. Defective print jobs must be removed from the queue with cancel.

If a print job is corrupted or an error occurs in the communication between the host and the printer, the printer cannot process the data correctly and prints numerous sheets of paper with unintelligible characters. To fix the problem, follow these steps:

  1. To stop printing, remove all paper from ink jet printers or open the paper trays of laser printers. High-quality printers have a button for canceling the current printout.

  2. The print job may still be in the queue, because jobs are only removed after they are sent completely to the printer. Use lpstat -o or lpstat -h cups.example.com -o to check which queue is currently printing. Delete the print job with cancel QUEUE-JOBNUMBER or cancel -h cups.example.com QUEUE-JOBNUMBER.

  3. Some data may still be transferred to the printer even though the print job has been deleted from the queue. Check if a CUPS back-end process is still running for the respective queue and terminate it.

  4. Reset the printer completely by switching it off for some time. Then insert the paper and turn on the printer.

17.8.8 Debugging CUPS

Use the following generic procedure to locate problems in CUPS:

  1. Set LogLevel debug in /etc/cups/cupsd.conf.

  2. Stop cupsd.

  3. Remove /var/log/cups/error_log* to avoid having to search through very large log files.

  4. Start cupsd.

  5. Repeat the action that led to the problem.

  6. Check the messages in /var/log/cups/error_log* to identify the cause of the problem.

17.8.9 For More Information

In-depth information about printing on SUSE Linux is presented in the openSUSE Support Database at http://en.opensuse.org/Portal:Printing. Solutions to many specific problems are presented in the SUSE Knowledgebase (http://www.suse.com/support/). Locate the relevant articles with a text search for CUPS.

18 The X Window System

  • Filename: x11.xml
  • ID: cha.x11

The X Window System (X11) is the de facto standard for graphical user interfaces in Unix. X is network-based, enabling applications started on one host to be displayed on another host connected over any kind of network (LAN or Internet). This chapter provides basic information on the X configuration, and background information about the use of fonts in SUSE® Linux Enterprise Server.

Usually, the X Window System needs no configuration. The hardware is dynamically detected during X start-up. The use of xorg.conf is therefore deprecated. If you still need to specify custom options to change the way X behaves, you can still do so by modifying configuration files under /etc/X11/xorg.conf.d/.

Tip
Tip: IBM z Systems: Configuring the Graphical User Interface

IBM z Systems does not have any input or output devices supported by X.Org. Therefore, none of the configuration procedures described in this section apply. More relevant information for IBM z Systems can be found in Chapter 4, Installation on IBM z Systems.

18.1 Installing and Configuring Fonts

  • Filename: x11_fonts.xml
  • ID: sec.x11.fontsys

Fonts in Linux can be categorized into two parts:

Outline or Vector Fonts

Contains a mathematical description as drawing instructions about the shape of a glyph. As such, each glyph can be scaled to arbitrary sizes without loss of quality. Before such a font (or glyph) can be used, the mathematical descriptions need to be transformed into a raster (grid). This process is called font rasterization. Font hinting (embedded inside the font) improves and optimizes the rendering result for a particular size. Rasterization and hinting is done with the FreeType library.

Common formats under Linux are PostScript Type 1 and Type 2, TrueType, and OpenType.

Bitmap or Raster Fonts

Consists of an array of pixels designed for a specific font size. Bitmap fonts are extremely fast and simple to render. However, compared to vector fonts, bitmap fonts cannot be scaled without losing quality. As such, these fonts are usually distributed in different sizes. These days, bitmap fonts are still used in the Linux console and sometimes in terminals.

Under Linux, Portable Compiled Format (PCF) or Glyph Bitmap Distribution Format (BDF) are the most common formats.

The appearance of these fonts can be influenced by two main aspects:

  • choosing a suitable font family,

  • rendering the font with an algorithm that achieves results comfortable for the receiver's eyes.

The last point is only relevant to vector fonts. Although the above two points are highly subjective, some defaults need to be created.

Linux font rendering systems consist of several libraries with different relations. The basic font rendering library is FreeType, which converts font glyphs of supported formats into optimized bitmap glyphs. The rendering process is controlled by an algorithm and its parameters (which may be subject to patent issues).

Every program or library which uses FreeType should consult the Fontconfig library. This library gathers font configuration from users and from the system. When a user amends his Fontconfig setting, this change will result in Fontconfig-aware applications.

More sophisticated OpenType shaping needed for scripts such as Arabic, Han or Phags-Pa and other higher level text processing is done using Harfbuzz or Pango.

18.1.1 Showing Installed Fonts

To get an overview about which fonts are installed on your system, ask the commands rpm or fc-list. Both will give you a good answer, but may return a different list depending on system and user configuration:

rpm

Invoke rpm to see which software packages containing fonts are installed on your system:

rpm -qa '*fonts*'

Every font package should satisfy this expression. However, the command may return some false positives like fonts-config (which is neither a font nor does it contain fonts).

fc-list

Invoke fc-list to get an overview about what font families can be accessed, whether they are installed on the system or in your home:

fc-list ':' family
Note
Note: Command fc-list

The command fc-list is a wrapper to the Fontconfig library. It is possible to query a lot of interesting information from Fontconfig—or, to be more precise, from its cache. See man 1 fc-list for more details.

18.1.2 Viewing Fonts

If you want to know what an installed font family looks like, either use the command ftview (package ft2demos) or visit http://fontinfo.opensuse.org/. For example, to display the FreeMono font in 14 point, use ftview like this:

ftview 14 /usr/share/fonts/truetype/FreeMono.ttf

If you need further information, go to http://fontinfo.opensuse.org/ to find out which styles (regular, bold, italic, etc.) and languages are supported.

18.1.3 Querying Fonts

To query which font is used when a pattern is given, use the fc-match command.

For example, if your pattern contains an already installed font, fc-match returns the file name, font family, and the style:

tux > fc-match 'Liberation Serif'
LiberationSerif-Regular.ttf: "Liberation Serif" "Regular"

If the desired font does not exist on your system, Fontconfig's matching rules take place and try to find the most similar fonts available. This means, your request is substituted:

tux > fc-match 'Foo Family'
DejaVuSans.ttf: "DejaVu Sans" "Book"

Fontconfig supports aliases: a name is substituted with another family name. A typical example are the generic names such as sans-serif, serif, and monospace. These alias names can be substituted by real family names or even a preference list of family names:

tux > for font in serif sans mono; do fc-match "$font" ; done
DejaVuSerif.ttf: "DejaVu Serif" "Book"
DejaVuSans.ttf: "DejaVu Sans" "Book"
DejaVuSansMono.ttf: "DejaVu Sans Mono" "Book"

The result may vary on your system, depending on which fonts are currently installed.

Note
Note: Similarity Rules according to Fontconfig

Fontconfig always returns a real family (if at least one is installed) according to the given request, as similar as possible. Similarity depends on Fontconfig's internal metrics and on the user's or administrator's Fontconfig settings.

18.1.4 Installing Fonts

To install a new font there are these major methods:

  1. Manually install the font files such as *.ttf or *.otf to a known font directory. If it needs to be system-wide, use the standard directory /usr/share/fonts. For installation in your home directory, use ~/.config/fonts.

    If you want to deviate from the standard directories, Fontconfig allows you to choose another one. Let Fontconfig know by using the <dir> element, see Section 18.1.5.2, “Diving into Fontconfig XML” for details.

  2. Install fonts using zypper. Lots of fonts are already available as a package, be it on your SUSE distribution or in the M17N:fonts repository. Add the repository to your list using the following command. For example, to add a repository for SLE 12:

    sudo zypper ar
         http://download.opensuse.org/repositories/M17N:/fonts/SLE_12_SP3/

    To search for your FONT_FAMILY_NAME use this command:

    sudo zypper se 'FONT_FAMILY_NAME*fonts'

18.1.5 Configuring the Appearance of Fonts

Depending on the rendering medium, and font size, the result may be unsatisfactory. For example, an average monitor these days has a resolution of 100dpi which makes pixels too big and glyphs look clunky.

There are several algorithms available to deal with low resolutions, such as anti-aliasing (grayscale smoothing), hinting (fitting to the grid), or subpixel rendering (tripling resolution in one direction). These algorithms can also differ from one font format to another.

Important
Important: Patent Issues with Subpixel Rendering

Subpixel rendering is not used in SUSE distributions. Although FreeType2 has support for this algorithm, it is covered by several patents expiring at the end of the year 2019. Therefore, setting subpixel rendering options in Fontconfig has no effect unless the system has a FreeType2 library with subpixel rendering compiled in.

Via Fontconfig, it is possible to select a rendering algorithms for every font individually or for a set of fonts.

18.1.5.1 Configuring Fonts via sysconfig

SUSE Linux Enterprise Server comes with a sysconfig layer above Fontconfig. This is a good starting point for experimenting with font configuration. To change the default settings, edit the configuration file /etc/sysconfig/fonts-config. (or use the YaST sysconfig module). After you have edited the file, run fonts-config:

sudo /usr/sbin/fonts-config

Restart the application to make the effect visible. Keep in mind the following issues:

  • A few applications do need not to be restarted. For example, Firefox re-reads Fontconfig configuration from time to time. Newly created or reloaded tabs get new font configurations later.

  • The fonts-config script is called automatically after every package installation or removal (if not, it is a bug of the font software package).

  • Every sysconfig variable can be temporarily overridden by the fonts-config command line option. See fonts-config --help for details.

There are several sysconfig variables which can be altered. See man 1 fonts-config or the help page of the YaST sysconfig module. The following variables are examples:

Usage of Rendering Algorithms

Consider FORCE_HINTSTYLE, FORCE_AUTOHINT, FORCE_BW, FORCE_BW_MONOSPACE, USE_EMBEDDED_BITMAPS and EMBEDDED_BITMAP_LANGAGES

Preference Lists of Generic Aliases

Use PREFER_SANS_FAMILIES, PREFER_SERIF_FAMILIES, PREFER_MONO_FAMILIES and SEARCH_METRIC_COMPATIBLE

The following list provides some configuration examples, sorted from the most readable fonts (more contrast) to most beautiful (more smoothed).

Bitmap Fonts

Prefer bitmap fonts via the PREFER_*_FAMILIES variables. Follow the example in the help section for these variables. Be aware that these fonts are rendered black and white, not smoothed and that bitmap fonts are available in several sizes only. Consider using

SEARCH_METRIC_COMPATIBLE="no"

to disable metric compatibility-driven family name substitutions.

Scalable Fonts Rendered Black and White

Scalable fonts rendered without antialiasing can result in a similar outcome to bitmap fonts, while maintaining font scalability. Use well hinted fonts like the Liberation families. Unfortunately, there is a lack of well hinted fonts though. Set the following variable to force this method:

FORCE_BW="yes"
Monospaced Fonts Rendered Black and White

Render monospaced fonts without antialiasing only, otherwise use default settings:

FORCE_BW_MONOSPACE="yes"
Default Settings

All fonts are rendered with antialiasing. Well hinted fonts will be rendered with the byte code interpreter (BCI) and the rest with autohinter (hintstyle=hintslight). Leave all relevant sysconfig variables to the default setting.

CFF Fonts

Use fonts in CFF format. They can be considered also more readable than the default TrueType fonts given the current improvements in FreeType2. Try them out by following the example of PREFER_*_FAMILIES. Possibly make them more dark and bold with:

SEARCH_METRIC_COMPATIBLE="no"

as they are rendered by hintstyle=hintslight by default. Also consider using:

SEARCH_METRIC_COMPATIBLE="no"
Autohinter Exclusively

Even for a well hinted font, use FreeType2's autohinter. That can lead to thicker, sometimes fuzzier letter shapes with lower contrast. Set the following variable to activate this:

FORCE_AUTOHINTER="yes"

Use FORCE_HINTSTYLE to control the level of hinting.

18.1.5.2 Diving into Fontconfig XML

Fontconfig's configuration format is the eXtensible Markup Language (XML). These few examples are not a complete reference, but a brief overview. Details and other inspiration can be found in man 5 fonts-conf or in /etc/fonts/conf.d/.

The central Fontconfig configuration file is /etc/fonts/fonts.conf, which—along other work—includes the whole /etc/fonts/conf.d/ directory. To customize Fontconfig, there are two places where you can insert your changes:

Fontconfig Configuration Files
  1. System-wide changes.  Edit the file /etc/fonts/local.conf (by default, it contains an empty fontconfig element).

  2. User-specific changes.  Edit the file ~/.config/fontconfig/fonts.conf. Place Fontconfig configuration files in the ~/.config/fontconfig/conf.d/ directory.

User-specific changes overwrite any system-wide settings.

Note
Note: Deprecated User Configuration File

The file ~/.fonts.conf is marked as deprecated and should not be used anymore. Use ~/.config/fontconfig/fonts.conf instead.

Every configuration file needs to have a fontconfig element. As such, the minimal file looks like this:

<?xml version="1.0"?>
   <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
   <fontconfig>
   <!-- Insert your changes here -->
   </fontconfig>

If the default directories are not enough, insert the dir element with the respective directory:

<dir>/usr/share/fonts2</dir>

Fontconfig searches recursively for fonts.

Font-rendering algorithms can be chosen with following Fontconfig snippet (see Example 18.1, “Specifying Rendering Algorithms”):

Example 18.1: Specifying Rendering Algorithms
<match target="font">
 <test name="family">
  <string>FAMILY_NAME</string>
 </test>
 <edit name="antialias" mode="assign">
  <bool>true</bool>
 </edit>
 <edit name="hinting" mode="assign">
  <bool>true</bool>
 </edit>
 <edit name="autohint" mode="assign">
  <bool>false</bool>
 </edit>
 <edit name="hintstyle" mode="assign">
  <const>hintfull</const>
 </edit>
</match>

Various properties of fonts can be tested. For example, the <test> element can test for the font family (as shown in the example), size interval, spacing, font format, and others. When abandoning <test> completely, all <edit> elements will be applied to every font (global change).

Example 18.2: Aliases and Family Name Substitutions
Rule 1
<alias>
 <family>Alegreya SC</family>
 <default>
  <family>serif</family>
 </default>
</alias>
Rule 2
<alias>
 <family>serif</family>
 <prefer>
  <family>Droid Serif</family>
 </prefer>
</alias>
Rule 3
<alias>
 <family>serif</family>
 <accept>
  <family>STIXGeneral</family>
 </accept>
</alias>

The rules from Example 18.2, “Aliases and Family Name Substitutions” create a prioritized family list (PFL). Depending on the element, different actions are performed:

<default> from Rule 1

This rule adds a serif family name at the end of the PFL.

<prefer> from Rule 2

This rule adds Droid Serif just before the first occurrence of serif in the PFL, whenever Alegreya SC is in PFL.

<accept> from Rule 3

This rule adds a STIXGeneral family name just after the first occurrence of the serif family name in the PFL.

Putting this together, when snippets occur in the order Rule 1 - Rule 2 - Rule 3 and the user requests Alegreya SC, then the PFL is created as depicted in Table 18.1, “Generating PFL from Fontconfig rules”.

Table 18.1: Generating PFL from Fontconfig rules

Order

Current PFL

Request

Alegreya SC

Rule 1

Alegreya SC, serif

Rule 2

Alegreya SC, Droid Serif, serif

Rule 3

Alegreya SC, Droid Serif, serif, STIXGeneral

In Fontconfig's metrics, the family name has the highest priority over other patterns, like style, size, etc. Fontconfig checks which family is currently installed on the system. If Alegreya SC is installed, then Fontconfig returns it. If not, it asks for Droid Serif, etc.

Be careful. When the order of Fontconfig snippets is changed, Fontconfig can return different results, as depicted in Table 18.2, “Results from Generating PFL from Fontconfig Rules with Changed Order”.

Table 18.2: Results from Generating PFL from Fontconfig Rules with Changed Order

Order

Current PFL

Note

Request

Alegreya SC

Same request performed.

Rule 2

Alegreya SC

serif not in FPL, nothing is substituted

Rule 3

Alegreya SC

serif not in FPL, nothing is substituted

Rule 1

Alegreya SC, serif

Alegreya SC present in FPL, substitution is performed

Note
Note: Implication.

Think of the <default> alias as a classification or inclusion of this group (if not installed). As the example shows, <default> should always precede the <prefer> and <accept> aliases of that group.

<default> classification is not limited to the generic aliases serif, sans-serif and monospace. See /usr/share/fontconfig/conf.avail/30-metric-aliases.conf for a complex example.

The following Fontconfig snippet in Example 18.3, “Aliases and Family Name Substitutions” creates a serif group. Every family in this group could substitute others when a former font is not installed.

Example 18.3: Aliases and Family Name Substitutions
<alias>
 <family>Alegreya SC</family>
 <default>
  <family>serif</family>
 </default>
</alias>
<alias>
 <family>Droid Serif</family>
 <default>
  <family>serif</family>
 </default>
</alias>
<alias>
 <family>STIXGeneral</family>
 <default>
  <family>serif</family>
 </default>
</alias>
<alias>
 <family>serif</family>
 <accept>
  <family>Droid Serif</family>
  <family>STIXGeneral</family>
  <family>Alegreya SC</family>
 </accept>
</alias>

Priority is given by the order in the <accept> alias. Similarly, stronger <prefer> aliases can be used.

Example 18.2, “Aliases and Family Name Substitutions” is expanded by Example 18.4, “Aliases and Family Names Substitutions”.

Example 18.4: Aliases and Family Names Substitutions
Rule 4
<alias>
 <family>serif</family>
 <accept>
  <family>Liberation Serif</family>
 </accept>
</alias>
Rule 5
<alias>
 <family>serif</family>
 <prefer>
  <family>DejaVu Serif</family>
 </prefer>
</alias>

The expanded configuration from Example 18.4, “Aliases and Family Names Substitutions” would lead to the following PFL evolution:

Table 18.3: Results from Generating PFL from Fontconfig Rules

Order

Current PFL

Request

Alegreya SC

Rule 1

Alegreya SC, serif

Rule 2

Alegreya SC, Droid Serif, serif

Rule 3

Alegreya SC, Droid Serif, serif, STIXGeneral

Rule 4

Alegreya SC, Droid Serif, serif, Liberation Serif, STIXGeneral

Rule 5

Alegreya SC, Droid Serif, DejaVu Serif, serif, Liberation Serif, STIXGeneral

Note
Note: Implications.
  • In case multiple <accept> declarations for the same generic name exist, the declaration that is parsed last wins. If possible, do not use <accept> after user (/etc/fonts/conf.d/*-user.conf) when creating a system-wide configuration.

  • In case multiple <prefer declarations for the same generic name exist, the declaration that is parsed last wins. If possible, do not use <prefer> before user in the system-wide configuration.

  • Every <prefer> declaration overwrites <accept> declarations for the same generic name. If the administrator wants to allow the user to utilize even <accept> and not only <prefer>,the administrator should not use <prefer> in the system-wide configuration. On the other hand, as users mostly use <prefer>, this should not have any detrimental effect. We also see the use of <prefer> also in system wide configurations.

18.2 For More Information

Install the packages xorg-docs to get more in-depth information about X11. man 5 xorg.conf tells you more about the format of the manual configuration (if needed). More information on the X11 development can be found on the project's home page at http://www.x.org.

Drivers are found in xf86-video-* packages, for example xf86-video-nv. Many of the drivers delivered with these packages are described in detail in the related manual page. For example, if you use the nv driver, find more information about this driver in man 4 nv.

Information about third-party drivers should be available in /usr/share/doc/packages/<package_name>. For example, the documentation of x11-video-nvidiaG03 is available in /usr/share/doc/packages/x11-video-nvidiaG03 after the package was installed.

19 Accessing File Systems with FUSE

  • Filename: fuse.xml
  • ID: cha.fuse
Abstract

FUSE is the acronym for file system in user space. This means you can configure and mount a file system as an unprivileged user. Normally, you need to be root for this task. FUSE alone is a kernel module. Combined with plug-ins, it allows you to extend FUSE to access almost all file systems like remote SSH connections, ISO images, and more.

19.1 Configuring FUSE

Before you can use FUSE, you need to install the package fuse. Depending which file system you want to use, you need additional plug-ins available as separate packages.

Generally you do not need to configure FUSE. However, it is a good idea to create a directory where all your mount points are combined. For example, you can create a directory ~/mounts and insert your subdirectories for your different file systems there.

19.2 Mounting an NTFS Partition

NTFS, the New Technology File System, is the default file system of Windows. Since under normal circumstances the unprivileged user cannot mount NTFS block devices using the external FUSE library, the process of mounting a Windows partition described below requires root privileges.

  1. Become root and install the package ntfs-3g. It is available in SUSE Linux Enterprise Workstation Extension.

  2. Create a directory that is to be used as a mount point, for example ~/mounts/windows.

  3. Find out which Windows partition you need. Use YaST and start the partitioner module to see which partition belongs to Windows, but do not modify anything. Alternatively, become root and execute /sbin/fdisk -l. Look for partitions with a partition type of HPFS/NTFS.

  4. Mount the partition in read-write mode. Replace the placeholder DEVICE with your respective Windows partition:

    ntfs-3g /dev/DEVICE MOUNT POINT

    To use your Windows partition in read-only mode, append -o ro:

    ntfs-3g /dev/DEVICE MOUNT POINT -o ro

    The command ntfs-3g uses the current user (UID) and group (GID) to mount the given device. If you want to set the write permissions to a different user, use the command id USER to get the output of the UID and GID values. Set it with:

    id tux
    uid=1000(tux) gid=100(users) groups=100(users),16(dialout),33(video)
    ntfs-3g /dev/DEVICE MOUNT POINT -o uid=1000,gid=100

    Find additional options in the man page.

To unmount the resource, run fusermount -u MOUNT POINT.

19.3 For More Information

See the home page http://fuse.sourceforge.net of FUSE for more information.

20 Managing Kernel Modules

  • Filename: kernel_modules.xml
  • ID: cha.mod

Although Linux is a monolithic kernel, it can be extended using kernel modules. These are special objects that can be inserted into the kernel and removed on demand. In practical terms, kernel modules make it possible to add and remove drivers and interfaces that are not included in the kernel itself. Linux provides several commands for managing kernel modules.

20.1 Listing Loaded Modules with lsmod and modinfo

Use the lsmod command to view what kernel modules are currently loaded. The output of the command may look as follows:

tux >  lsmod
Module                  Size  Used by
snd_usb_audio         188416  2
snd_usbmidi_lib        36864  1 snd_usb_audio
hid_plantronics        16384  0
snd_rawmidi            36864  1 snd_usbmidi_lib
snd_seq_device         16384  1 snd_rawmidi
fuse                  106496  3
nfsv3                  45056  1
nfs_acl                16384  1 nfsv3

The output is divided into three columns. The Module column lists the names of the loaded modules, while the Size column displays the size of each module. The Used by column shows the number of referring modules and their names. Note that this list may be incomplete.

To view detailed information about a specific kernel module, use the modinfo MODULE_NAME command, where MODULE_NAME is the name of the desired kernel module. Note that the modinfo binary resides in the /sbin directory that is not in the user's PATH environment variable. This means that you must specify the full path to the binary when running modinfo command as a regular user:

$ /sbin/modinfo kvm
filename:       /lib/modules/4.4.57-18.3-default/kernel/arch/x86/kvm/kvm.ko
license:        GPL
author:         Qumranet
srcversion:     BDFD8098BEEA517CB75959B
depends:        irqbypass
intree:         Y
vermagic:       4.4.57-18.3-default SMP mod_unload modversions
signer:         openSUSE Secure Boot Signkey
sig_key:        03:32:FA:9C:BF:0D:88:BF:21:92:4B:0D:E8:2A:09:A5:4D:5D:EF:C8
sig_hashalgo:   sha256
parm:           ignore_msrs:bool
parm:           min_timer_period_us:uint
parm:           kvmclock_periodic_sync:bool
parm:           tsc_tolerance_ppm:uint
parm:           lapic_timer_advance_ns:uint
parm:           halt_poll_ns:uint
parm:           halt_poll_ns_grow:int
parm:           halt_poll_ns_shrink:int

20.2 Adding and Removing Kernel Modules

While it is possible to use insmod and rmmod to add and remove kernel modules, it is recommended to use the modprobe tool instead. modprobe offers several important advantages, including automatic dependency resolution and blacklisting.

When used without any parameters, the modprobe command installs a specified kernel module. modprobe must be run with root privileges:

tux > sudo modprobe acpi

To remove a kernel module, use the -r parameter:

sudo modprobe -r acpi

20.2.1 Loading Kernel Modules Automatically on Boot

Instead of loading kernel modules manually, you can load them automatically during the boot process using the system-modules-load.service service. To enable a kernel module, add a .conf file to the /etc/modules-load.d/ directory. It is good practice to give the configuration file the same name as the module, for example:

/etc/modules-load.d/rt2800usb.conf

The configuration file must contain the name of the desired kernel module (for example, rt2800usb).

The described technique allows you to load kernel modules without any parameters. If you need to load a kernel module with specific options, add a configuration file to the /etc/modprobe.d/ directory instead. The file must have the .conf extension. The name of the file should adhere to the following naming convention: priority-modulename.conf, for example: 50-thinkfan.conf. The configuration file must contain the name of the kernel module and the desired parameters. You can use the example command below to create a configuration file containing the name of the kernel module and its parameters:

echo "options thinkpad_acpi fan_control=1" | sudo tee /etc/modprobe.d/thinkfan.conf
Note
Note: Loading Kernel Modules

Most kernel modules are loaded by the system automatically when a device is detected or user space requests specific functionality. Thus, adding modules manually to /etc/modules-load.d/ is rarely required.

20.2.2 Blacklisting Kernel Modules with modprobe

Blacklisting a kernel module prevents it from loading during the boot process. This can be useful when you want to disable a module that you suspect is causing problems on your system. Note that you can still load blacklisted kernel modules manually using the insmod or modprobe tools.

To blacklist a module, add the blacklist MODULE_NAME line to the /etc/modprobe.d/50-blacklist.conf file. For example:

blacklist nouveau

Run the mkinitrd command as root to generate a new initrd image, then reboot your machine. These steps can be performed using the following command:

su
echo "blacklist nouveau" >> /etc/modprobe.d/50-blacklist.conf && mkinitrd && reboot

To disable a kernel module temporarily only, blacklist it on-the-fly during the boot. To do this, press the E key when you see the boot screen. This drops you into a minimal editor that allows you to modify boot parameters. Locate the line that looks as follows:

linux /boot/vmlinuz...splash= silent quiet showopts

Add the modprobe.blacklist=MODULE_NAME command to the end of the line. For example:

linux /boot/vmlinuz...splash= silent quiet showopts modprobe.blacklist=nouveau

Press F10 or CtrlX to boot with the specified configuration.

To blacklist a kernel module permanently via GRUB, open the /etc/default/grub file for editing, and add the modprobe.blacklist=MODULE_NAME option to the GRUB_CMD_LINUX command. Then run the sudo grub2-mkconfig -o /boot/grub2/grub.cfg command to enable the changes.

21 Dynamic Kernel Device Management with udev

  • Filename: udev.xml
  • ID: cha.udev

The kernel can add or remove almost any device in a running system. Changes in the device state (whether a device is plugged in or removed) need to be propagated to user space. Devices need to be configured when they are plugged in and recognized. Users of a certain device need to be informed about any changes in this device's recognized state. udev provides the needed infrastructure to dynamically maintain the device node files and symbolic links in the /dev directory. udev rules provide a way to plug external tools into the kernel device event processing. This allows you to customize udev device handling by adding certain scripts to execute as part of kernel device handling, or request and import additional data to evaluate during device handling.

21.1 The /dev Directory

The device nodes in the /dev directory provide access to the corresponding kernel devices. With udev, the /dev directory reflects the current state of the kernel. Every kernel device has one corresponding device file. If a device is disconnected from the system, the device node is removed.

The content of the /dev directory is kept on a temporary file system and all files are rendered at every system start-up. Manually created or modified files do not, by design, survive a reboot. Static files and directories that should always be in the /dev directory regardless of the state of the corresponding kernel device can be created with systemd-tmpfiles. The configuration files are found in /usr/lib/tmpfiles.d/ and /etc/tmpfiles.d/; for more information, see the systemd-tmpfiles(8) man page.

21.2 Kernel uevents and udev

The required device information is exported by the sysfs file system. For every device the kernel has detected and initialized, a directory with the device name is created. It contains attribute files with device-specific properties.

Every time a device is added or removed, the kernel sends a uevent to notify udev of the change. The udev daemon reads and parses all provided rules from the /etc/udev/rules.d/*.rules files once at start-up and keeps them in memory. If rules files are changed, added or removed, the daemon can reload the in-memory representation of all rules with the command udevadm control --reload. For more details on udev rules and their syntax, refer to Section 21.6, “Influencing Kernel Device Event Handling with udev Rules”.

Every received event is matched against the set of provides rules. The rules can add or change event environment keys, request a specific name for the device node to create, add symbolic links pointing to the node or add programs to run after the device node is created. The driver core uevents are received from a kernel netlink socket.

21.3 Drivers, Kernel Modules and Devices

The kernel bus drivers probe for devices. For every detected device, the kernel creates an internal device structure while the driver core sends a uevent to the udev daemon. Bus devices identify themselves by a specially-formatted ID, which tells what kind of device it is. Usually these IDs consist of vendor and product ID and other subsystem-specific values. Every bus has its own scheme for these IDs, called MODALIAS. The kernel takes the device information, composes a MODALIAS ID string from it and sends that string along with the event. For a USB mouse, it looks like this:

MODALIAS=usb:v046DpC03Ed2000dc00dsc00dp00ic03isc01ip02

Every device driver carries a list of known aliases for devices it can handle. The list is contained in the kernel module file itself. The program depmod reads the ID lists and creates the file modules.alias in the kernel's /lib/modules directory for all currently available modules. With this infrastructure, module loading is as easy as calling modprobe for every event that carries a MODALIAS key. If modprobe $MODALIAS is called, it matches the device alias composed for the device with the aliases provided by the modules. If a matching entry is found, that module is loaded. All this is automatically triggered by udev.

21.4 Booting and Initial Device Setup

All device events happening during the boot process before the udev daemon is running are lost, because the infrastructure to handle these events resides on the root file system and is not available at that time. To cover that loss, the kernel provides a uevent file located in the device directory of every device in the sysfs file system. By writing add to that file, the kernel resends the same event as the one lost during boot. A simple loop over all uevent files in /sys triggers all events again to create the device nodes and perform device setup.

As an example, a USB mouse present during boot may not be initialized by the early boot logic, because the driver is not available at that time. The event for the device discovery was lost and failed to find a kernel module for the device. Instead of manually searching for connected devices, udev requests all device events from the kernel after the root file system is available, so the event for the USB mouse device runs again. Now it finds the kernel module on the mounted root file system and the USB mouse can be initialized.

From user space, there is no visible difference between a device coldplug sequence and a device discovery during runtime. In both cases, the same rules are used to match and the same configured programs are run.

21.5 Monitoring the Running udev Daemon

The program udevadm monitor can be used to visualize the driver core events and the timing of the udev event processes.

UEVENT[1185238505.276660] add   /devices/pci0000:00/0000:00:1d.2/usb3/3-1 (usb)
UDEV  [1185238505.279198] add   /devices/pci0000:00/0000:00:1d.2/usb3/3-1 (usb)
UEVENT[1185238505.279527] add   /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0 (usb)
UDEV  [1185238505.285573] add   /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0 (usb)
UEVENT[1185238505.298878] add   /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10 (input)
UDEV  [1185238505.305026] add   /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10 (input)
UEVENT[1185238505.305442] add   /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10/mouse2 (input)
UEVENT[1185238505.306440] add   /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10/event4 (input)
UDEV  [1185238505.325384] add   /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10/event4 (input)
UDEV  [1185238505.342257] add   /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10/mouse2 (input)

The UEVENT lines show the events the kernel has sent over netlink. The UDEV lines show the finished udev event handlers. The timing is printed in microseconds. The time between UEVENT and UDEV is the time udev took to process this event or the udev daemon has delayed its execution to synchronize this event with related and already running events. For example, events for hard disk partitions always wait for the main disk device event to finish, because the partition events may rely on the data that the main disk event has queried from the hardware.

udevadm monitor --env shows the complete event environment:

ACTION=add
DEVPATH=/devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10
SUBSYSTEM=input
SEQNUM=1181
NAME="Logitech USB-PS/2 Optical Mouse"
PHYS="usb-0000:00:1d.2-1/input0"
UNIQ=""
EV=7
KEY=70000 0 0 0 0
REL=103
MODALIAS=input:b0003v046DpC03Ee0110-e0,1,2,k110,111,112,r0,1,8,amlsfw

udev also sends messages to syslog. The default syslog priority that controls which messages are sent to syslog is specified in the udev configuration file /etc/udev/udev.conf. The log priority of the running daemon can be changed with udevadm control --log_priority=LEVEL/NUMBER.

21.6 Influencing Kernel Device Event Handling with udev Rules

A udev rule can match any property the kernel adds to the event itself or any information that the kernel exports to sysfs. The rule can also request additional information from external programs. Every event is matched against all provided rules. All rules are located in the /etc/udev/rules.d directory.

Every line in the rules file contains at least one key value pair. There are two kinds of keys, match and assignment keys. If all match keys match their values, the rule is applied and the assignment keys are assigned the specified value. A matching rule may specify the name of the device node, add symbolic links pointing to the node or run a specified program as part of the event handling. If no matching rule is found, the default device node name is used to create the device node. Detailed information about the rule syntax and the provided keys to match or import data are described in the udev man page. The following example rules provide a basic introduction to udev rule syntax. The example rules are all taken from the udev default rule set that is located under /etc/udev/rules.d/50-udev-default.rules.

Example 21.1: Example udev Rules
# console
KERNEL=="console", MODE="0600", OPTIONS="last_rule"

# serial devices
KERNEL=="ttyUSB*", ATTRS{product}=="[Pp]alm*Handheld*", SYMLINK+="pilot"

# printer
SUBSYSTEM=="usb", KERNEL=="lp*", NAME="usb/%k", SYMLINK+="usb%k", GROUP="lp"

# kernel firmware loader
SUBSYSTEM=="firmware", ACTION=="add", RUN+="firmware.sh"

The console rule consists of three keys: one match key (KERNEL) and two assign keys (MODE, OPTIONS). The KERNEL match rule searches the device list for any items of the type console. Only exact matches are valid and trigger this rule to be executed. The MODE key assigns special permissions to the device node, in this case, read and write permissions to the owner of this device only. The OPTIONS key makes this rule the last rule to be applied to any device of this type. Any later rule matching this particular device type does not have any effect.

The serial devices rule is not available in 50-udev-default.rules anymore, but it is still worth considering. It consists of two match keys (KERNEL and ATTRS) and one assign key (SYMLINK). The KERNEL key searches for all devices of the ttyUSB type. Using the * wild card, this key matches several of these devices. The second match key, ATTRS, checks whether the product attribute file in sysfs for any ttyUSB device contains a certain string. The assign key (SYMLINK) triggers the addition of a symbolic link to this device under /dev/pilot. The operator used in this key (+=) tells udev to additionally perform this action, even if previous or later rules add other symbolic links. As this rule contains two match keys, it is only applied if both conditions are met.

The printer rule deals with USB printers and contains two match keys which must both apply to get the entire rule applied (SUBSYSTEM and KERNEL). Three assign keys deal with the naming for this device type (NAME), the creation of symbolic device links (SYMLINK) and the group membership for this device type (GROUP). Using the * wild card in the KERNEL key makes it match several lp printer devices. Substitutions are used in both, the NAME and the SYMLINK keys to extend these strings by the internal device name. For example, the symbolic link to the first lp USB printer would read /dev/usblp0.

The kernel firmware loader rule makes udev load additional firmware by an external helper script during runtime. The SUBSYSTEM match key searches for the firmware subsystem. The ACTION key checks whether any device belonging to the firmware subsystem has been added. The RUN+= key triggers the execution of the firmware.sh script to locate the firmware that is to be loaded.

Some general characteristics are common to all rules:

  • Each rule consists of one or more key value pairs separated by a comma.

  • A key's operation is determined by the operator. udev rules support several operators.

  • Each given value must be enclosed by quotation marks.

  • Each line of the rules file represents one rule. If a rule is longer than one line, use \ to join the different lines as you would do in shell syntax.

  • udev rules support a shell-style pattern that matches the *, ?, and [] patterns.

  • udev rules support substitutions.

21.6.1 Using Operators in udev Rules

Creating keys you can choose from several operators, depending on the type of key you want to create. Match keys will normally be used to find a value that either matches or explicitly mismatches the search value. Match keys contain either of the following operators:

==

Compare for equality. If the key contains a search pattern, all results matching this pattern are valid.

!=

Compare for non-equality. If the key contains a search pattern, all results matching this pattern are valid.

Any of the following operators can be used with assign keys:

=

Assign a value to a key. If the key previously consisted of a list of values, the key resets and only the single value is assigned.

+=

Add a value to a key that contains a list of entries.

:=

Assign a final value. Disallow any later change by later rules.

21.6.2 Using Substitutions in udev Rules

udev rules support the use of placeholders and substitutions. Use them in a similar fashion as you would do in any other scripts. The following substitutions can be used with udev rules:

%r, $root

The device directory, /dev by default.

%p, $devpath

The value of DEVPATH.

%k, $kernel

The value of KERNEL or the internal device name.

%n, $number

The device number.

%N, $tempnode

The temporary name of the device file.

%M, $major

The major number of the device.

%m, $minor

The minor number of the device.

%s{ATTRIBUTE}, $attr{ATTRIBUTE}

The value of a sysfs attribute (specified by ATTRIBUTE).

%E{VARIABLE}, $env{VARIABLE}

The value of an environment variable (specified by VARIABLE).

%c, $result

The output of PROGRAM.

%%

The % character.

$$

The $ character.

21.6.3 Using udev Match Keys

Match keys describe conditions that must be met before a udev rule can be applied. The following match keys are available:

ACTION

The name of the event action, for example, add or remove when adding or removing a device.

DEVPATH

The device path of the event device, for example, DEVPATH=/bus/pci/drivers/ipw3945 to search for all events related to the ipw3945 driver.

KERNEL

The internal (kernel) name of the event device.

SUBSYSTEM

The subsystem of the event device, for example, SUBSYSTEM=usb for all events related to USB devices.

ATTR{FILENAME}

sysfs attributes of the event device. To match a string contained in the vendor attribute file name, you could use ATTR{vendor}=="On[sS]tream", for example.

KERNELS

Let udev search the device path upwards for a matching device name.

SUBSYSTEMS

Let udev search the device path upwards for a matching device subsystem name.

DRIVERS

Let udev search the device path upwards for a matching device driver name.

ATTRS{FILENAME}

Let udev search the device path upwards for a device with matching sysfs attribute values.

ENV{KEY}

The value of an environment variable, for example, ENV{ID_BUS}="ieee1394 to search for all events related to the FireWire bus ID.

PROGRAM

Let udev execute an external program. To be successful, the program must return with exit code zero. The program's output, printed to STDOUT, is available to the RESULT key.

RESULT

Match the output string of the last PROGRAM call. Either include this key in the same rule as the PROGRAM key or in a later one.

21.6.4 Using udev Assign Keys

In contrast to the match keys described above, assign keys do not describe conditions that must be met. They assign values, names and actions to the device nodes maintained by udev.

NAME

The name of the device node to be created. After a rule has set a node name, all other rules with a NAME key for this node are ignored.

SYMLINK

The name of a symbolic link related to the node to be created. Multiple matching rules can add symbolic links to be created with the device node. You can also specify multiple symbolic links for one node in one rule using the space character to separate the symbolic link names.

OWNER, GROUP, MODE

The permissions for the new device node. Values specified here overwrite anything that has been compiled in.

ATTR{KEY}

Specify a value to be written to a sysfs attribute of the event device. If the == operator is used, this key is also used to match against the value of a sysfs attribute.

ENV{KEY}

Tell udev to export a variable to the environment. If the == operator is used, this key is also used to match against an environment variable.

RUN

Tell udev to add a program to the list of programs to be executed for this device. Keep in mind to restrict this to very short tasks to avoid blocking further events for this device.

LABEL

Add a label where a GOTO can jump to.

GOTO

Tell udev to skip several rules and continue with the one that carries the label referenced by the GOTO key.

IMPORT{TYPE}

Load variables into the event environment such as the output of an external program. udev imports variables of several types. If no type is specified, udev tries to determine the type itself based on the executable bit of the file permissions.

  • program tells udev to execute an external program and import its output.

  • file tells udev to import a text file.

  • parent tells udev to import the stored keys from the parent device.

WAIT_FOR_SYSFS

Tells udev to wait for the specified sysfs file to be created for a certain device. For example, WAIT_FOR_SYSFS="ioerr_cnt" informs udev to wait until the ioerr_cnt file has been created.

OPTIONS

The OPTION key may have several values:

  • last_rule tells udev to ignore all later rules.

  • ignore_device tells udev to ignore this event completely.

  • ignore_remove tells udev to ignore all later remove events for the device.

  • all_partitions tells udev to create device nodes for all available partitions on a block device.

21.7 Persistent Device Naming

The dynamic device directory and the udev rules infrastructure make it possible to provide stable names for all disk devices—regardless of their order of recognition or the connection used for the device. Every appropriate block device the kernel creates is examined by tools with special knowledge about certain buses, drive types or file systems. Along with the dynamic kernel-provided device node name, udev maintains classes of persistent symbolic links pointing to the device:

/dev/disk
|-- by-id
|   |-- scsi-SATA_HTS726060M9AT00_MRH453M4HWHG7B -> ../../sda
|   |-- scsi-SATA_HTS726060M9AT00_MRH453M4HWHG7B-part1 -> ../../sda1
|   |-- scsi-SATA_HTS726060M9AT00_MRH453M4HWHG7B-part6 -> ../../sda6
|   |-- scsi-SATA_HTS726060M9AT00_MRH453M4HWHG7B-part7 -> ../../sda7
|   |-- usb-Generic_STORAGE_DEVICE_02773 -> ../../sdd
|   `-- usb-Generic_STORAGE_DEVICE_02773-part1 -> ../../sdd1
|-- by-label
|   |-- Photos -> ../../sdd1
|   |-- SUSE10 -> ../../sda7
|   `-- devel -> ../../sda6
|-- by-path
|   |-- pci-0000:00:1f.2-scsi-0:0:0:0 -> ../../sda
|   |-- pci-0000:00:1f.2-scsi-0:0:0:0-part1 -> ../../sda1
|   |-- pci-0000:00:1f.2-scsi-0:0:0:0-part6 -> ../../sda6
|   |-- pci-0000:00:1f.2-scsi-0:0:0:0-part7 -> ../../sda7
|   |-- pci-0000:00:1f.2-scsi-1:0:0:0 -> ../../sr0
|   |-- usb-02773:0:0:2 -> ../../sdd
|   |-- usb-02773:0:0:2-part1 -> ../../sdd1
`-- by-uuid
    |-- 159a47a4-e6e6-40be-a757-a629991479ae -> ../../sda7
    |-- 3e999973-00c9-4917-9442-b7633bd95b9e -> ../../sda6
    `-- 4210-8F8C -> ../../sdd1

21.8 Files used by udev

/sys/*

Virtual file system provided by the Linux kernel, exporting all currently known devices. This information is used by udev to create device nodes in /dev

/dev/*

Dynamically created device nodes and static content created with systemd-tmpfiles; for more information, see the systemd-tmpfiles(8) man page.

The following files and directories contain the crucial elements of the udev infrastructure:

/etc/udev/udev.conf

Main udev configuration file.

/etc/udev/rules.d/*

udev event matching rules.

/usr/lib/tmpfiles.d/ and /etc/tmpfiles.d/

Responsible for static /dev content.

/usr/lib/udev/*

Helper programs called from udev rules.

21.9 For More Information

For more information about the udev infrastructure, refer to the following man pages:

udev

General information about udev, keys, rules and other important configuration issues.

udevadm

udevadm can be used to control the runtime behavior of udev, request kernel events, manage the event queue and provide simple debugging mechanisms.

udevd

Information about the udev event managing daemon.

22 Live Patching the Linux Kernel Using kGraft

  • Filename: kgraft.xml
  • ID: cha.kgraft
Abstract

This document describes the basic principles of the kGraft live patching technology and provides usage guidelines for the SLE Live Patching service.

kGraft is a live patching technology for runtime patching of the Linux kernel, without stopping the kernel. This maximizes system uptime, and thus system availability, which is important for mission-critical systems. By allowing dynamic patching of the kernel, the technology also encourages users to install critical security updates without deferring them to a scheduled downtime.

A kGraft patch is a kernel module, intended for replacing whole functions in the kernel. kGraft primarily offers in-kernel infrastructure for integration of the patched code with base kernel code at runtime.

SLE Live Patching is a service provided on top of regular SUSE Linux Enterprise Server maintenance. kGraft patches distributed through SLE Live Patching supplement regular SLES maintenance updates. Common update stack and procedures can be used for SLE Live Patching deployment.

The information provided in this document related to the AMD64/Intel 64 and POWER architectures. In case you use a different architecture, the procedures may differ.

22.1 Advantages of kGraft

Live kernel patching using kGraft is especially useful for quick response in emergencies (when serious vulnerabilities are known and should be fixed when possible or there are serious system stability issues with a known fix). It is not used for scheduled updates where time is not critical.

Typical use cases for kGraft include systems like memory databases with huge amounts of RAM, where boot-up times of 15 minutes or more are not uncommon, large simulations that need weeks or months without a restart, or infrastructure building blocks providing continuous service to a many consumers.

The main advantage of kGraft is that it never requires stopping the kernel, not even for a short time period.

A kGraft patch is a .ko kernel module in a RPM package. It is inserted into the kernel using the insmod command when the package is installed or updated. kGraft replaces whole functions in the kernel, even if they are being executed. An updated kGraft module can replace an existing patch if necessary.

kGraft is also lean—it contains only a small amount of code, because it leverages other standard Linux technologies.

22.2 Low-level Function of kGraft

kGraft uses the ftrace infrastructure to perform patching. The following describes the implementation on the AMD64/Intel 64 architecture.

To patch a kernel function, kGraft needs some space at the start of the function to insert a jump to a new function. This space is allocated during kernel compilation by GCC with function profiling turned on. In particular, a 5-byte call instruction is injected to the start of kernel functions. When such instrumented kernel is booting, profiling calls are replaced by 5-byte NOP (no operation) instructions.

After patching starts, the first byte is replaced by the INT3 (breakpoint) instruction. This ensures atomicity of the 5-byte instruction replacement. The other four bytes are replaced by the address to the new function. Finally, the first byte is replaced by the JMP (long jump) opcode.

Inter-processor non-maskable interrupts (IPI NMI) are used throughout the process to flush speculative decoding queues of other CPUs in the system. This allows switching to the new function without ever stopping the kernel, not even for a very short moment. The interruptions by IPI NMIs can be measured in microseconds and are not considered service interruptions as they happen while the kernel is running in any case.

Callers are never patched. Instead, the callee's NOPs are replaced by a JMP to the new function. JMP instructions remain forever. This takes care of function pointers, including in structures, and does not require saving any old data for the possibility of un-patching.

However, these steps alone would not be good enough: since the functions would be replaced non-atomically, a new fixed function in one part of the kernel could still be calling an old function elsewhere or vice versa. If the semantics of the function interfaces changed in the patch, chaos would ensue.

Thus, until all functions are replaced, kGraft uses an approach based on trampolines and similar to RCU (read-copy-update), to ensure a consistent view of the world to each user space thread, kernel thread and kernel interrupt. A per-thread flag is set on each kernel entry and exit. This way, an old function would always call another old function and a new function always a new one. Once all processes have the "new universe" flag set, patching is complete, trampolines can be removed and the code can operate at full speed without performance impact other than an extra-long jump for each patched function.

22.3 Installing kGraft Patches

This section describes the activation of the SUSE Linux Enterprise Live Patching extension and the installation of kGraft patches.

22.3.1 Activation of SLE Live Patching

To activate SLE Live Patching on your system, follow these steps:

  1. If your SLES system is not yet registered, register it. Registration can be done during the system installation or later using the YaST Product Registration module (yast2 registration). After registration, click Yes to see the list of available online updates.

    If your SLES system is already registered, but SLE Live Patching is not yet activated, open the YaST Product Registration module (yast2 registration) and click Select Extensions.

  2. Select SUSE Linux Enterprise Live Patching 12 in the list of available extensions and click Next.

  3. Confirm the license terms and click Next.

  4. Enter the SLE Live Patching registration code and click Next.

  5. Check the Installation Summary and selected Patterns. The pattern Live Patching should be selected for installation.

  6. Click Accept to complete the installation. This will install the base kGraft components on your system together with the initial live patch.

22.3.2 Updating System

  1. SLE Live Patching updates are distributed in a form that allows using standard SLE update stack for patch application. The initial live patch can be updated using zypper patch, YaST Online Update or equivalent method.

  2. The kernel is patched automatically during the package installation. However, invocations of the old kernel functions are not completely eliminated until all sleeping processes wake up and get out of the way. This can take a considerable amount of time. Despite this, sleeping processes that use the old kernel functions are not considered a security issue. Nevertheless, in the current version of kGraft, it is not possible to apply another kGraft patch until all processes cross the kernel-user space boundary to stop using patched functions from the previous patch.

    To see the global status of patching, check the flag in /sys/kernel/kgraft/in_progress. The value 1 signifies the existence of sleeping processes that still need to be woken (the patching is still in progress). The value 0 signifies that all processes are using solely the patched functions and patching has finished already. Alternatively, use the kgr status command to obtain the same information.

    The flag can be checked on a per-process basis too. Check the number in /proc/PROCESS_NUMBER/kgr_in_progress for each process individually. Again, the value 1 signifies sleeping process that still needs to be woken. Alternatively, use the kgr blocking command to output the list of sleeping processes.

22.4 Patch Lifecycle

Expiration dates of live patches can be accessed with zypper lifecycle. Make sure that the package lifecycle-data-sle-live-patching is installed.

tux > zypper lifecycle

Product end of support
Codestream: SUSE Linux Enterprise Server 12             2024-10-31
SUSE Linux Enterprise Server 12 SP2                     n/a*

Extension end of support
SUSE Linux Enterprise Live Patching                     2017-10-31

Package end of support if different from product:
SUSEConnect                              Now, installed 0.2.41-18.1, update available 0.2.42-19.3.1
apache2-utils                            Now


*) See https://www.suse.com/lifecycle  for latest information

When the expiration date of a patch is reached, no further live patches for this kernel version will be supplied. Plan an update of your kernel before the end of the live patch lifecycle period.

22.5 Removing a kGraft Patch

To remove a kGraft patch, use the following procedure:

  1. First remove the patch itself using Zypper:

    zypper rm kgraft-patch-3_12_32-25-default
  2. Then reboot the machine.

22.6 Stuck Kernel Execution Threads

Kernel threads need to be prepared to handle kGraft. Third-party software may not be ready for kGraft adoption and its kernel modules may spawn kernel execution threads. These threads will block the patching process indefinitely. As an emergency measure kGraft offers the possibility to force finishing of the patching process without waiting for all execution threads to cross the safety checkpoint. This can be achieved by writing 0 into /sys/kernel/kgraft/in_progress. Consult SUSE Support before performing this procedure.

22.7 The kgr Tool

Several kGraft management tasks can be simplified with the kgr tool. The available commands are:

kgr status

Displays the overall status of kGraft patching (ready or in_progress).

kgr patches

Displays the list of loaded kGraft patches.

kgr blocking

Lists processes that are preventing kGraft patching from finishing. By default only the PIDs are listed. Specifying -v prints command lines if available. Another -v displays also stack traces.

For detailed information, see man kgr.

22.8 Scope of kGraft Technology

kGraft is based on replacing functions. Data structure alteration can be accomplished only indirectly with kGraft. As a result, changes to kernel data structure require special care and, if the change is too large, rebooting might be required. kGraft also might not be able to handle situations where one compiler is used to compile the old kernel and another compiler is used for compiling the patch.

Because of the way kGraft works, support for third-party modules that are spawning kernel threads is limited.

22.9 Scope of SLE Live Patching

Fixes for SUSE Common Vulnerability Scoring System (CVSS) level 7+ vulnerabilities and bug fixes related to system stability or data corruption will be shipped in the scope of SLE Live Patching. It might not be possible to produce a live patch for all kinds of fixes fulfilling the above criteria. SUSE reserves the right to skip fixes where production of a kernel live patch is unviable because of technical reasons. For more information on CVSS 3.0, which is the base for the SUSE CVSS rating, see https://www.first.org/cvss/.

22.10 Interaction with the Support Processes

While resolving a technical difficulty with SUSE Support, you may receive a so-called Program Temporary Fix (PTF). PTFs may be issued for various packages including those forming the base of SLE Live Patching.

kGraft PTFs complying with the conditions described in the previous section can be installed as usual and SUSE will ensure that the system in question does not need to be rebooted and that future live updates are applied cleanly.

PTFs issued for the base kernel disrupt the live patching process. First, installing the PTF kernel means a reboot as the kernel cannot be replaced as a whole at runtime. Second, another reboot is needed to replace the PTF with any regular maintenance updates for which the live patches are issued.

PTFs for other packages in SLE Live Patching can be treated like regular PTFs with the usual guarantees.

23 Special System Features

  • Filename: suse_linux.xml
  • ID: cha.suse
Abstract

This chapter starts with information about various software packages, the virtual consoles and the keyboard layout. We talk about software components like bash, cron and logrotate, because they were changed or enhanced during the last release cycles. Even if they are small or considered of minor importance, users should change their default behavior, because these components are often closely coupled with the system. The chapter concludes with a section about language and country-specific settings (I18N and L10N).

23.1 Information about Special Software Packages

  • Filename: suse_sw_packages.xml
  • ID: sec.suse.packages

The programs bash, cron, logrotate, locate, ulimit and free are very important for system administrators and many users. Man pages and info pages are two useful sources of information about commands, but both are not always available. GNU Emacs is a popular and very configurable text editor.

23.1.1 The bash Package and /etc/profile

Bash is the default system shell. When used as a login shell, it reads several initialization files. Bash processes them in the order they appear in this list:

  1. /etc/profile

  2. ~/.profile

  3. /etc/bash.bashrc

  4. ~/.bashrc

Make custom settings in ~/.profile or ~/.bashrc. To ensure the correct processing of these files, it is necessary to copy the basic settings from /etc/skel/.profile or /etc/skel/.bashrc into the home directory of the user. It is recommended to copy the settings from /etc/skel after an update. Execute the following shell commands to prevent the loss of personal adjustments:

mv ~/.bashrc ~/.bashrc.old
cp /etc/skel/.bashrc ~/.bashrc
mv ~/.profile ~/.profile.old
cp /etc/skel/.profile ~/.profile

Then copy personal adjustments back from the *.old files.

23.1.2 The cron Package

Use cron to run commands automatically in the background at predefined time. cron uses specially formatted time tables, and the tool comes with several default ones. Users can also specify custom tables, if needed.

The cron tables are located in /var/spool/cron/tabs. /etc/crontab serves as a systemwide cron table. Enter the user name to run the command directly after the time table and before the command. In Example 23.1, “Entry in /etc/crontab”, root is entered. Package-specific tables, located in /etc/cron.d, have the same format. See the cron man page (man cron).

Example 23.1: Entry in /etc/crontab
1-59/5 * * * *   root   test -x /usr/sbin/atrun && /usr/sbin/atrun

You cannot edit /etc/crontab by calling the command crontab -e. This file must be loaded directly into an editor, then modified and saved.

A number of packages install shell scripts to the directories /etc/cron.hourly, /etc/cron.daily, /etc/cron.weekly and /etc/cron.monthly, whose execution is controlled by /usr/lib/cron/run-crons. /usr/lib/cron/run-crons is run every 15 minutes from the main table (/etc/crontab). This guarantees that processes that may have been neglected can be run at the proper time.

To run the hourly, daily or other periodic maintenance scripts at custom times, remove the time stamp files regularly using /etc/crontab entries (see Example 23.2, “/etc/crontab: Remove Time Stamp Files”, which removes the hourly one before every full hour, the daily one once a day at 2:14 a.m., etc.).

Example 23.2: /etc/crontab: Remove Time Stamp Files
59 *  * * *     root  rm -f /var/spool/cron/lastrun/cron.hourly
14 2  * * *     root  rm -f /var/spool/cron/lastrun/cron.daily
29 2  * * 6     root  rm -f /var/spool/cron/lastrun/cron.weekly
44 2  1 * *     root  rm -f /var/spool/cron/lastrun/cron.monthly

Or you can set DAILY_TIME in /etc/sysconfig/cron to the time at which cron.daily should start. The setting of MAX_NOT_RUN ensures that the daily tasks get triggered to run, even if the user did not turn on the computer at the specified DAILY_TIME for a longer time. The maximum value of MAX_NOT_RUN is 14 days.

The daily system maintenance jobs are distributed to various scripts for reasons of clarity. They are contained in the package aaa_base. /etc/cron.daily contains, for example, the components suse.de-backup-rpmdb, suse.de-clean-tmp or suse.de-cron-local.

23.1.3 Stopping Cron Status Messages

To avoid the mail-flood caused by cron status messages, the default value of SEND_MAIL_ON_NO_ERROR in /etc/sysconfig/cron is set to "no" for new installations. Even with this setting to "no", cron data output will still be sent to the MAILTO address, as documented in the cron man page.

In the update case it is recommended to set these values according to your needs.

23.1.4 Log Files: Package logrotate

  • Filename: suse_logfiles.xml
  • ID: sec.suse.log

There are several system services (daemons) that, along with the kernel itself, regularly record the system status and specific events onto log files. This way, the administrator can regularly check the status of the system at a certain point in time, recognize errors or faulty functions and troubleshoot them with pinpoint precision. These log files are normally stored in /var/log as specified by FHS and grow on a daily basis. The logrotate package helps control the growth of these files. For more details refer to Section 3.3, “Managing Log Files with logrotate.

23.1.5 The locate Command

locate, a command for quickly finding files, is not included in the standard scope of installed software. If desired, install the package mlocate, the successor of the package findutils-locate. The updatedb process is started automatically every night or about 15 minutes after booting the system.

23.1.6 The ulimit Command

With the ulimit (user limits) command, it is possible to set limits for the use of system resources and to have these displayed. ulimit is especially useful for limiting available memory for applications. With this, an application can be prevented from co-opting too much of the system resources and slowing or even hanging up the operating system.

ulimit can be used with various options. To limit memory usage, use the options listed in Table 23.1, “ulimit: Setting Resources for the User”.

Table 23.1: ulimit: Setting Resources for the User

-m

The maximum resident set size

-v

The maximum amount of virtual memory available to the shell

-s

The maximum size of the stack

-c

The maximum size of core files created

-a

All current limits are reported

Systemwide default entries are set in /etc/profile. Editing this file directly is not recommended, because changes will be overwritten during system upgrades. To customize systemwide profile settings, use /etc/profile.local. Per-user settings should be made in ~USER/.bashrc.

Example 23.3: ulimit: Settings in ~/.bashrc
# Limits maximum resident set size (physical memory):
ulimit -m 98304

# Limits of virtual memory:
ulimit -v 98304

Memory allocations must be specified in KB. For more detailed information, see man bash.

Important
Important: ulimit Support

Not all shells support ulimit directives. PAM (for example, pam_limits) offers comprehensive adjustment possibilities as an alternative to ulimit.

23.1.7 The free Command

The free command displays the total amount of free and used physical memory as well as swap space in the system and the buffers and cache consumed by the kernel. The concept of available RAM dates back to before the days of unified memory management. The slogan free memory is bad memory applies well to Linux. As a result, Linux has always made the effort to balance out caches without actually allowing free or unused memory.

The kernel does not have direct knowledge of any applications or user data. Instead, it manages applications and user data in a page cache. If memory runs short, parts of it are written to the swap partition or to files, from which they can initially be read using the mmap command (see man mmap).

The kernel also contains other caches, such as the slab cache, where the caches used for network access are stored. This may explain the differences between the counters in /proc/meminfo. Most, but not all, of them can be accessed via /proc/slabinfo.

However, if your goal is to find out how much RAM is currently being used, find this information in /proc/meminfo.

23.1.8 Man Pages and Info Pages

For some GNU applications (such as tar), the man pages are no longer maintained. For these commands, use the --help option to get a quick overview of the info pages, which provide more in-depth instructions. Info is GNU's hypertext system. Read an introduction to this system by entering info info. Info pages can be viewed with Emacs by entering emacs -f info or directly in a console with info. You can also use tkinfo, xinfo or the help system to view info pages.

23.1.9 Selecting Man Pages Using the man Command

To read a man page enter man MAN_PAGE. If a man page with the same name exists in different sections, they will all be listed with the corresponding section numbers. Select the one to display. If you do not enter a section number within a few seconds, the first man page will be displayed.

To change this to the default system behavior, set MAN_POSIXLY_CORRECT=1 in a shell initialization file such as ~/.bashrc.

23.1.10 Settings for GNU Emacs

  • Filename: suse_emacs.xml
  • ID: sec.suse.emacs

GNU Emacs is a complex work environment. The following sections cover the configuration files processed when GNU Emacs is started. More information is available at http://www.gnu.org/software/emacs/.

On start-up, Emacs reads several files containing the settings of the user, system administrator and distributor for customization or preconfiguration. The initialization file ~/.emacs is installed to the home directories of the individual users from /etc/skel. .emacs, in turn, reads the file /etc/skel/.gnu-emacs. To customize the program, copy .gnu-emacs to the home directory (with cp /etc/skel/.gnu-emacs ~/.gnu-emacs) and make the desired settings there.

.gnu-emacs defines the file ~/.gnu-emacs-custom as custom-file. If users make settings with the customize options in Emacs, the settings are saved to ~/.gnu-emacs-custom.

With SUSE Linux Enterprise Server, the emacs package installs the file site-start.el in the directory /usr/share/emacs/site-lisp. The file site-start.el is loaded before the initialization file ~/.emacs. Among other things, site-start.el ensures that special configuration files distributed with Emacs add-on packages, such as psgml, are loaded automatically. Configuration files of this type are located in /usr/share/emacs/site-lisp, too, and always begin with suse-start-. The local system administrator can specify systemwide settings in default.el.

More information about these files is available in the Emacs info file under Init File: info:/emacs/InitFile. Information about how to disable the loading of these files (if necessary) is also provided at this location.

The components of Emacs are divided into several packages:

  • The base package emacs.

  • emacs-x11 (usually installed): the program with X11 support.

  • emacs-nox: the program without X11 support.

  • emacs-info: online documentation in info format.

  • emacs-el: the uncompiled library files in Emacs Lisp. These are not required at runtime.

  • Numerous add-on packages can be installed if needed: emacs-auctex (LaTeX), psgml (SGML and XML), gnuserv (client and server operation) and others.

23.2 Virtual Consoles

  • Filename: suse_vc.xml
  • ID: sec.suse.virt.konsolen

Linux is a multiuser and multitasking system. The advantages of these features can be appreciated even on a stand-alone PC system. In text mode, there are six virtual consoles available. Switch between them using AltF1 through AltF6. The seventh console is reserved for X and the tenth console shows kernel messages.

To switch to a console from X without shutting it down, use CtrlAltF1 to CtrlAltF6. To return to X, press AltF7.

23.3 Keyboard Mapping

  • Filename: suse_kb.xml
  • ID: sec.suse.kb

To standardize the keyboard mapping of programs, changes were made to the following files:

/etc/inputrc
/etc/X11/Xmodmap
/etc/skel/.emacs
/etc/skel/.gnu-emacs
/etc/skel/.vimrc
/etc/csh.cshrc
/etc/termcap
/usr/share/terminfo/x/xterm
/usr/share/X11/app-defaults/XTerm
/usr/share/emacs/VERSION/site-lisp/term/*.el

These changes only affect applications that use terminfo entries or whose configuration files are changed directly (vi, emacs, etc.). Applications not shipped with the system should be adapted to these defaults.

Under X, the compose key (multikey) can be enabled as explained in /etc/X11/Xmodmap.

Further settings are possible using the X Keyboard Extension (XKB). This extension is also used by the desktop environment GNOME (gswitchit).

Tip
Tip: For More Information

Information about XKB is available in the documents listed in /usr/share/doc/packages/xkeyboard-config (part of the xkeyboard-config package).

23.4 Language and Country-Specific Settings

  • Filename: suse_l10n.xml
  • ID: sec.suse.l10n

The system is, to a very large extent, internationalized and can be modified for local needs. Internationalization (I18N) allows specific localization (L10N). The abbreviations I18N and L10N are derived from the first and last letters of the words and, in between, the number of letters omitted.

Settings are made with LC_ variables defined in the file /etc/sysconfig/language. This refers not only to native language support, but also to the categories Messages (Language), Character Set, Sort Order, Time and Date, Numbers and Money. Each of these categories can be defined directly with its own variable or indirectly with a master variable in the file language (see the locale man page).

RC_LC_MESSAGES, RC_LC_CTYPE, RC_LC_COLLATE, RC_LC_TIME, RC_LC_NUMERIC, RC_LC_MONETARY

These variables are passed to the shell without the RC_ prefix and represent the listed categories. The shell profiles concerned are listed below. The current setting can be shown with the command locale.

RC_LC_ALL

This variable, if set, overwrites the values of the variables already mentioned.

RC_LANG

If none of the previous variables are set, this is the fallback. By default, only RC_LANG is set. This makes it easier for users to enter their own values.

ROOT_USES_LANG

A yes or no variable. If set to no, root always works in the POSIX environment.

The variables can be set with the YaST sysconfig editor. The value of such a variable contains the language code, country code, encoding and modifier. The individual components are connected by special characters:

  LANG=<language>[[_<COUNTRY>].<Encoding>[@<Modifier>]]

23.4.1 Some Examples

You should always set the language and country codes together. Language settings follow the standard ISO 639 available at http://www.evertype.com/standards/iso639/iso639-en.html and http://www.loc.gov/standards/iso639-2/. Country codes are listed in ISO 3166, see http://en.wikipedia.org/wiki/ISO_3166.

It only makes sense to set values for which usable description files can be found in /usr/lib/locale. Additional description files can be created from the files in /usr/share/i18n using the command localedef. The description files are part of the glibc-i18ndata package. A description file for en_US.UTF-8 (for English and United States) can be created with:

localedef -i en_US -f UTF-8 en_US.UTF-8
LANG=en_US.UTF-8

This is the default setting if American English is selected during installation. If you selected another language, that language is enabled but still with UTF-8 as the character encoding.

LANG=en_US.ISO-8859-1

This sets the language to English, country to United States and the character set to ISO-8859-1. This character set does not support the Euro sign, but it can be useful sometimes for programs that have not been updated to support UTF-8. The string defining the charset (ISO-8859-1 in this case) is then evaluated by programs like Emacs.

LANG=en_IE@euro

The above example explicitly includes the Euro sign in a language setting. This setting is obsolete now, as UTF-8 also covers the Euro symbol. It is only useful if an application supports ISO-8859-15 and not UTF-8.

Changes to /etc/sysconfig/language are activated by the following process chain:

  • For the Bash: /etc/profile reads /etc/profile.d/lang.sh which, in turn, analyzes /etc/sysconfig/language.

  • For tcsh: At login, /etc/csh.login reads /etc/profile.d/lang.csh which, in turn, analyzes /etc/sysconfig/language.

This ensures that any changes to /etc/sysconfig/language are available at the next login to the respective shell, without having to manually activate them.

Users can override the system defaults by editing their ~/.bashrc accordingly. For example, if you do not want to use the system-wide en_US for program messages, include LC_MESSAGES=es_ES so that messages are displayed in Spanish instead.

23.4.2 Locale Settings in ~/.i18n

If you are not satisfied with locale system defaults, change the settings in ~/.i18n according to the Bash scripting syntax. Entries in ~/.i18n override system defaults from /etc/sysconfig/language. Use the same variable names but without the RC_ name space prefixes. For example, use LANG instead of RC_LANG:

LANG=cs_CZ.UTF-8
LC_COLLATE=C

23.4.3 Settings for Language Support

Files in the category Messages are, as a rule, only stored in the corresponding language directory (like en) to have a fallback. If you set LANG to en_US and the message file in /usr/share/locale/en_US/LC_MESSAGES does not exist, it falls back to /usr/share/locale/en/LC_MESSAGES.

A fallback chain can also be defined, for example, for Breton to French or for Galician to Spanish to Portuguese:

LANGUAGE="br_FR:fr_FR"

LANGUAGE="gl_ES:es_ES:pt_PT"

If desired, use the Norwegian variants Nynorsk and Bokmål instead (with additional fallback to no):

LANG="nn_NO"

LANGUAGE="nn_NO:nb_NO:no"

or

LANG="nb_NO"

LANGUAGE="nb_NO:nn_NO:no"

Note that in Norwegian, LC_TIME is also treated differently.

One problem that can arise is a separator used to delimit groups of digits not being recognized properly. This occurs if LANG is set to only a two-letter language code like de, but the definition file glibc uses is located in /usr/share/lib/de_DE/LC_NUMERIC. Thus LC_NUMERIC must be set to de_DE to make the separator definition visible to the system.

23.4.4 For More Information

Part IV Services

24 Time Synchronization with NTP

The NTP (network time protocol) mechanism is a protocol for synchronizing the system time over the network. First, a machine can obtain the time from a server that is a reliable time source. Second, a machine can itself act as a time source for other computers in the network. The goal is twofold—maintaining the absolute time and synchronizing the system time of all machines within a network.

25 The Domain Name System

DNS (domain name system) is needed to resolve the domain names and host names into IP addresses. In this way, the IP address 192.168.2.100 is assigned to the host name jupiter, for example. Before setting up your own name server, read the general information about DNS in Section 16.3, “Name Resolution”. The following configuration examples refer to BIND, the default DNS server.

26 DHCP

The purpose of the Dynamic Host Configuration Protocol (DHCP) is to assign network settings centrally (from a server) rather than configuring them locally on every workstation. A host configured to use DHCP does not have control over its own static address. It is enabled to configure itself completely and automatically according to directions from the server. If you use the NetworkManager on the client side, you do not need to configure the client. This is useful if you have changing environments and only one interface active at a time. Never use NetworkManager on a machine that runs a DHCP server.

27 Sharing File Systems with NFS

Distributing and sharing file systems over a network is a common task in corporate environments. The well-proven network file system (NFS) works with NIS, the yellow pages protocol. For a more secure protocol that works with LDAP and Kerberos, check NFSv4 (default). Combined with pNFS, you can eliminate performance bottlenecks.

NFS with NIS makes a network transparent to the user. With NFS, it is possible to distribute arbitrary file systems over the network. With an appropriate setup, users always find themselves in the same environment regardless of the terminal they currently use.

28 Samba

Using Samba, a Unix machine can be configured as a file and print server for macOS, Windows, and OS/2 machines. Samba has developed into a fully-fledged and rather complex product. Configure Samba with YaST, or by editing the configuration file manually.

29 On-Demand Mounting with Autofs

autofs is a program that automatically mounts specified directories on an on-demand basis. It is based on a kernel module for high efficiency, and can manage both local directories and network shares. These automatic mount points are mounted only when they are accessed, and unmounted after a certain period of inactivity. This on-demand behavior saves bandwidth and results in better performance than static mounts managed by /etc/fstab. While autofs is a control script, automount is the command (daemon) that does the actual auto-mounting.

30 SLP

Configuring a network client requires detailed knowledge about services provided over the network (such as printing or LDAP, for example). To make it easier to configure such services on a network client, the service location protocol (SLP) was developed. SLP makes the availability and configuration data of selected services known to all clients in the local network. Applications that support SLP can use this information to be configured automatically.

31 The Apache HTTP Server

According to the survey from http://www.netcraft.com/, the Apache HTTP Server (Apache) is the world's most widely-used Web server. Developed by the Apache Software Foundation (http://www.apache.org/), it is available for most operating systems. SUSE® Linux Enterprise Server includes Apache version 2.4. In this chapter, learn how to install, configure and set up a Web server; how to use SSL, CGI, and additional modules; and how to troubleshoot Apache.

32 Setting Up an FTP Server with YaST

Using the YaST FTP Server module, you can configure your machine to function as an FTP (File Transfer Protocol) server. Anonymous and/or authenticated users can connect to your machine and download files using the FTP protocol. Depending on the configuration, they can also upload files to the FTP server. YaST uses vsftpd (Very Secure FTP Daemon).

33 The Proxy Server Squid

Squid is a widely-used proxy cache for Linux and Unix platforms. This means that it stores requested Internet objects, such as data on a Web or FTP server, on a machine that is closer to the requesting workstation than the server. It can be set up in multiple hierarchies to assure optimal response times and low bandwidth usage, even in modes that are transparent to end users. Additional software like squidGuard can be used to filter Web content.

34 Web Based Enterprise Management Using SFCB

24 Time Synchronization with NTP

  • Filename: net_xntp.xml
  • ID: cha.netz.xntp
Abstract

The NTP (network time protocol) mechanism is a protocol for synchronizing the system time over the network. First, a machine can obtain the time from a server that is a reliable time source. Second, a machine can itself act as a time source for other computers in the network. The goal is twofold—maintaining the absolute time and synchronizing the system time of all machines within a network.

Maintaining an exact system time is important in many situations. The built-in hardware clock does often not meet the requirements of applications such as databases or clusters. Manual correction of the system time would lead to severe problems because, for example, a backward leap can cause malfunction of critical applications. Within a network, it is usually necessary to synchronize the system time of all machines, but manual time adjustment is a bad approach. NTP provides a mechanism to solve these problems. The NTP service continuously adjusts the system time with reliable time servers in the network. It further enables the management of local reference clocks, such as radio-controlled clocks.

24.1 Configuring an NTP Client with YaST

The NTP daemon (ntpd) coming with the ntp package is preset to use the local computer clock as a time reference. Using the hardware clock, however, only serves as a fallback for cases where no time source of better precision is available. YaST simplifies the configuration of an NTP client.

24.1.1 Basic Configuration

The YaST NTP client configuration (Network Services › NTP Configuration) consists of tabs. Set the start mode of ntpd and the server to query on the General Settings tab.

Only Manually

Select Only Manually, if you want to manually start the ntpd daemon.

Synchronize without Daemon

Select Synchronize without Daemon to set the system time periodically without a permanently running ntpd. You can set the Interval of the Synchronization in Minutes.

Now and On Boot

Select Now and On Boot to start ntpd automatically when the system is booted. This setting is recommended.

24.1.2 Changing Basic Configuration

The servers and other time sources for the client to query are listed in the lower part of the General Settings tab. Modify this list as needed with Add, Edit, and Delete. Display Log provides the possibility to view the log files of your client.

Click Add to add a new source of time information. In the following dialog, select the type of source with which the time synchronization should be made. The following options are available:

YaST: NTP Server
Figure 24.1: YaST: NTP Server
Server

In the drop-down Select list (see Figure 24.1, “YaST: NTP Server”), determine whether to set up time synchronization using a time server from your local network (Local NTP Server) or an Internet-based time server that takes care of your time zone (Public NTP Server). For a local time server, click Lookup to start an SLP query for available time servers in your network. Select the most suitable time server from the list of search results and exit the dialog with OK. For a public time server, select your country (time zone) and a suitable server from the list under Public NTP Server then exit the dialog with OK. In the main dialog, test the availability of the selected server with Test. Options allows you to specify additional options for ntpd.

Using Access Control Options, you can restrict the actions that the remote computer can perform with the daemon running on your computer. This field is enabled only after checking Restrict NTP Service to Configured Servers Only on the Security Settings tab (see Figure 24.2, “Advanced NTP Configuration: Security Settings”). The options correspond to the restrict clauses in /etc/ntp.conf. For example, nomodify notrap noquery disallows the server to modify NTP settings of your computer and to use the trap facility (a remote event logging feature) of your NTP daemon. Using these restrictions is recommended for servers out of your control (for example, on the Internet).

Refer to /usr/share/doc/packages/ntp-doc (part of the ntp-doc package) for detailed information.

Peer

A peer is a machine to which a symmetric relationship is established: it acts both as a time server and as a client. To use a peer in the same network instead of a server, enter the address of the system. The rest of the dialog is identical to the Server dialog.

Radio Clock

To use a radio clock in your system for the time synchronization, enter the clock type, unit number, device name, and other options in this dialog. Click Driver Calibration to fine-tune the driver. Detailed information about the operation of a local radio clock is available in /usr/share/doc/packages/ntp-doc/refclock.html.

Outgoing Broadcast

Time information and queries can also be transmitted by broadcast in the network. In this dialog, enter the address to which such broadcasts should be sent. Do not activate broadcasting unless you have a reliable time source like a radio controlled clock.

Incoming Broadcast

If you want your client to receive its information via broadcast, enter the address from which the respective packets should be accepted in this fields.

Advanced NTP Configuration: Security Settings
Figure 24.2: Advanced NTP Configuration: Security Settings

In the Security Settings tab (see Figure 24.2, “Advanced NTP Configuration: Security Settings”), determine whether ntpd should be started in a chroot jail. By default, Run NTP Daemon in Chroot Jail is not activated. The chroot jail option increases the security in the event of an attack over ntpd, as it prevents the attacker from compromising the entire system.

Restrict NTP Service to Configured Servers Only increases the security of your system by disallowing remote computers to view and modify NTP settings of your computer and to use the trap facility for remote event logging. After being enabled, these restrictions apply to all remote computers, unless you override the access control options for individual computers in the list of time sources in the General Settings tab. For all other remote computers, only querying for local time is allowed.

Enable Open Port in Firewall if SuSEFirewall2 is active (which it is by default). If you leave the port closed, it is not possible to establish a connection to the time server.

24.2 Manually Configuring NTP in the Network

The easiest way to use a time server in the network is to set server parameters. For example, if a time server called ntp.example.com is reachable from the network, add its name to the file /etc/ntp.conf by adding the following line:

server ntp.example.com

To add more time servers, insert additional lines with the keyword server. After initializing ntpd with the command systemctl start ntp, it takes about one hour until the time is stabilized and the drift file for correcting the local computer clock is created. With the drift file, the systematic error of the hardware clock can be computed when the computer is powered on. The correction is used immediately, resulting in a higher stability of the system time.

There are two possible ways to use the NTP mechanism as a client: First, the client can query the time from a known server in regular intervals. With many clients, this approach can cause a high load on the server. Second, the client can wait for NTP broadcasts sent out by broadcast time servers in the network. This approach has the disadvantage that the quality of the server is unknown and a server sending out wrong information can cause severe problems.

If the time is obtained via broadcast, you do not need the server name. In this case, enter the line broadcastclient in the configuration file /etc/ntp.conf. To use one or more known time servers exclusively, enter their names in the line starting with servers.

24.3 Dynamic Time Synchronization at Runtime

If the system boots without network connection, ntpd starts up, but it cannot resolve DNS names of the time servers set in the configuration file. This can happen if you use NetworkManager with an encrypted Wi-Fi.

If you want ntpd to resolve DNS names at runtime, you must set the dynamic option. When a network connection is established after booting, ntpd looks up the names again and can reach the time servers to get the time.

Manually edit /etc/ntp.conf and add dynamic to one or more server entries:

server ntp.example.com dynamic

Or use YaST and proceed as follows:

  1. In YaST click Network Services › NTP Configuration.

  2. Select the server you want to configure. Then click Edit.

  3. Activate the Options field and add dynamic. Separate it with a space, if there are already other options entered.

  4. Click Ok to close the edit dialog. Repeat the previous step to change all servers as wanted.

  5. Finally click Ok to save the settings.

24.4 Setting Up a Local Reference Clock

The software package ntpd contains drivers for connecting local reference clocks. A list of supported clocks is available in the ntp-doc package in the file /usr/share/doc/packages/ntp-doc/refclock.html. Every driver is associated with a number. In NTP, the actual configuration takes place by means of pseudo IP addresses. The clocks are entered in the file /etc/ntp.conf as though they existed in the network. For this purpose, they are assigned special IP addresses in the form 127.127.T.U. Here, T stands for the type of the clock and determines which driver is used and U for the unit, which determines the interface used.

Normally, the individual drivers have special parameters that describe configuration details. The file /usr/share/doc/packages/ntp-doc/drivers/driverNN.html (where NN is the number of the driver) provides information about the particular type of clock. For example, the type 8 clock (radio clock over serial interface) requires an additional mode that specifies the clock more precisely. The Conrad DCF77 receiver module, for example, has mode 5. To use this clock as a preferred reference, specify the keyword prefer. The complete server line for a Conrad DCF77 receiver module would be:

server 127.127.8.0 mode 5 prefer

Other clocks follow the same pattern. Following the installation of the ntp-doc package, the documentation for NTP is available in the directory /usr/share/doc/packages/ntp-doc. The file /usr/share/doc/packages/ntp-doc/refclock.html provides links to the driver pages describing the driver parameters.

24.5 Clock Synchronization to an External Time Reference (ETR)

Support for clock synchronization to an external time reference (ETR) is available. The external time reference sends an oscillator signal and a synchronization signal every 2**20 (2 to the power of 20) microseconds to keep TOD clocks of all connected servers synchronized.

For availability two ETR units can be connected to a machine. If the clock deviates for more than the sync-check tolerance all CPUs get a machine check that indicates that the clock is out of sync. If this happens, all DASD I/O to XRC enabled devices is stopped until the clock is synchronized again.

The ETR support is activated via two sysfs attributes; run the following commands as root:

echo 1 > /sys/devices/system/etr/etr0/online
echo 1 > /sys/devices/system/etr/etr1/online

25 The Domain Name System

  • Filename: net_dns.xml
  • ID: cha.dns
Abstract

DNS (domain name system) is needed to resolve the domain names and host names into IP addresses. In this way, the IP address 192.168.2.100 is assigned to the host name jupiter, for example. Before setting up your own name server, read the general information about DNS in Section 16.3, “Name Resolution”. The following configuration examples refer to BIND, the default DNS server.

25.1 DNS Terminology

Zone

The domain name space is divided into regions called zones. For example, if you have example.com, you have the example section (or zone) of the com domain.

DNS server

The DNS server is a server that maintains the name and IP information for a domain. You can have a primary DNS server for master zone, a secondary server for slave zone, or a slave server without any zones for caching.

Master zone DNS server

The master zone includes all hosts from your network and a DNS server master zone stores up-to-date records for all the hosts in your domain.

Slave zone DNS server

A slave zone is a copy of the master zone. The slave zone DNS server obtains its zone data with zone transfer operations from its master server. The slave zone DNS server responds authoritatively for the zone as long as it has valid (not expired) zone data. If the slave cannot obtain a new copy of the zone data, it stops responding for the zone.

Forwarder

Forwarders are DNS servers to which your DNS server should send queries it cannot answer. To enable different configuration sources in one configuration, netconfig is used (see also man 8 netconfig).

Record

The record is information about name and IP address. Supported records and their syntax are described in BIND documentation. Some special records are:

NS record

An NS record tells name servers which machines are in charge of a given domain zone.

MX record

The MX (mail exchange) records describe the machines to contact for directing mail across the Internet.

SOA record

SOA (Start of Authority) record is the first record in a zone file. The SOA record is used when using DNS to synchronize data between multiple computers.

25.2 Installation

To install a DNS server, start YaST and select Software › Software Management. Choose View › Patterns and select DHCP and DNS Server. Confirm the installation of the dependent packages to finish the installation process.

Alternatively use the following command on the command line:

zypper in -t pattern dhcp_dns_server

25.3 Configuration with YaST

Use the YaST DNS module to configure a DNS server for the local network. When starting the module for the first time, a wizard starts, prompting you to make a few decisions concerning administration of the server. Completing this initial setup produces a basic server configuration. Use the expert mode to deal with more advanced configuration tasks, such as setting up ACLs, logging, TSIG keys, and other options.

25.3.1 Wizard Configuration

The wizard consists of three steps or dialogs. At the appropriate places in the dialogs, you can enter the expert configuration mode.

  1. When starting the module for the first time, the Forwarder Settings dialog, shown in Figure 25.1, “DNS Server Installation: Forwarder Settings”, opens. The Local DNS Resolution Policy allows to set the following options:

    • Merging forwarders is disabled

    • Automatic merging

    • Merging forwarders is enabled

    • Custom configuration—If Custom configuration is selected, Custom policy can be specified; by default (with Automatic merging selected), Custom policy is set to auto, but here you can either set interface names or select from the two special policy names STATIC and STATIC_FALLBACK.

    In Local DNS Resolution Forwarder, specify which service to use: Using system name servers, This name server (bind), or Local dnsmasq server.

    For more information about all these settings, see man 8 netconfig.

    DNS Server Installation: Forwarder Settings
    Figure 25.1: DNS Server Installation: Forwarder Settings

    Forwarders are DNS servers to which your DNS server sends queries it cannot answer itself. Enter their IP address and click Add.

  2. The DNS Zones dialog consists of several parts and is responsible for the management of zone files, described in Section 25.6, “Zone Files”. For a new zone, provide a name for it in Name. To add a reverse zone, the name must end in .in-addr.arpa. Finally, select the Type (master, slave, or forward). See Figure 25.2, “DNS Server Installation: DNS Zones”. Click Edit to configure other settings of an existing zone. To remove a zone, click Delete.

    DNS Server Installation: DNS Zones
    Figure 25.2: DNS Server Installation: DNS Zones
  3. In the final dialog, you can open the DNS port in the firewall by clicking Open Port in Firewall. Then decide whether to start the DNS server when booting (On or Off). You can also activate LDAP support. See Figure 25.3, “DNS Server Installation: Finish Wizard”.

    DNS Server Installation: Finish Wizard
    Figure 25.3: DNS Server Installation: Finish Wizard

25.3.2 Expert Configuration

After starting the module, YaST opens a window displaying several configuration options. Completing it results in a DNS server configuration with the basic functions in place:

25.3.2.1 Start-Up

Under Start-Up, define whether the DNS server should be started when the booting the system or manually. To start the DNS server immediately, click Start DNS Server Now. To stop the DNS server, click Stop DNS Server Now. To save the current settings, select Save Settings and Reload DNS Server Now. You can open the DNS port in the firewall with Open Port in Firewall and modify the firewall settings with Firewall Details.

By selecting LDAP Support Active, the zone files are managed by an LDAP database. Any changes to zone data written to the LDAP database are picked up by the DNS server when it is restarted or prompted to reload its configuration.

25.3.2.2 Forwarders

If your local DNS server cannot answer a request, it tries to forward the request to a Forwarder, if configured so. This forwarder may be added manually to the Forwarder List. If the forwarder is not static like in dial-up connections, netconfig handles the configuration. For more information about netconfig, see man 8 netconfig.

25.3.2.3 Basic Options

In this section, set basic server options. From the Option menu, select the desired item then specify the value in the corresponding text box. Include the new entry by selecting Add.

25.3.2.4 Logging

To set what the DNS server should log and how, select Logging. Under Log Type, specify where the DNS server should write the log data. Use the system-wide log by selecting System Log or specify a different file by selecting File. In the latter case, additionally specify a name, the maximum file size in megabytes and the number of log file versions to store.

Further options are available under Additional Logging. Enabling Log All DNS Queries causes every query to be logged, in which case the log file could grow extremely large. For this reason, it is not a good idea to enable this option for other than debugging purposes. To log the data traffic during zone updates between DHCP and DNS server, enable Log Zone Updates. To log the data traffic during a zone transfer from master to slave, enable Log Zone Transfer. See Figure 25.4, “DNS Server: Logging”.

DNS Server: Logging
Figure 25.4: DNS Server: Logging

25.3.2.5 ACLs

Use this dialog to define ACLs (access control lists) to enforce access restrictions. After providing a distinct name under Name, specify an IP address (with or without netmask) under Value in the following fashion:

{ 192.168.1/24; }

The syntax of the configuration file requires that the address ends with a semicolon and is put into curly braces.

25.3.2.6 TSIG Keys

The main purpose of TSIGs (transaction signatures) is to secure communications between DHCP and DNS servers. They are described in Section 25.8, “Secure Transactions”.

To generate a TSIG key, enter a distinctive name in the field labeled Key ID and specify the file where the key should be stored (Filename). Confirm your choices with Generate.

To use a previously created key, leave the Key ID field blank and select the file where it is stored under Filename. After that, confirm with Add.

25.3.2.7 DNS Zones (Adding a Slave Zone)

To add a slave zone, select DNS Zones, choose the zone type Slave, write the name of the new zone, and click Add.

In the Zone Editor sub-dialog under Master DNS Server IP, specify the master from which the slave should pull its data. To limit access to the server, select one of the ACLs from the list.

25.3.2.8 DNS Zones (Adding a Master Zone)

To add a master zone, select DNS Zones, choose the zone type Master, write the name of the new zone, and click Add. When adding a master zone, a reverse zone is also needed. For example, when adding the zone example.com that points to hosts in a subnet 192.168.1.0/24, you should also add a reverse zone for the IP-address range covered. By definition, this should be named 1.168.192.in-addr.arpa.

25.3.2.9 DNS Zones (Editing a Master Zone)

To edit a master zone, select DNS Zones, select the master zone from the table, and click Edit. The dialog consists of several pages: Basics (the one opened first), NS Records, MX Records, SOA, and Records.

The basic dialog, shown in Figure 25.5, “DNS Server: Zone Editor (Basics)”, lets you define settings for dynamic DNS and access options for zone transfers to clients and slave name servers. To permit the dynamic updating of zones, select Allow Dynamic Updates as well as the corresponding TSIG key. The key must have been defined before the update action starts. To enable zone transfers, select the corresponding ACLs. ACLs must have been defined already.

In the Basics dialog, select whether to enable zone transfers. Use the listed ACLs to define who can download zones.

DNS Server: Zone Editor (Basics)
Figure 25.5: DNS Server: Zone Editor (Basics)
Zone Editor (NS Records)

The NS Records dialog allows you to define alternative name servers for the zones specified. Make sure that your own name server is included in the list. To add a record, enter its name under Name Server to Add then confirm with Add. See Figure 25.6, “DNS Server: Zone Editor (NS Records)”.

DNS Server: Zone Editor (NS Records)
Figure 25.6: DNS Server: Zone Editor (NS Records)
Zone Editor (MX Records)

To add a mail server for the current zone to the existing list, enter the corresponding address and priority value. After doing so, confirm by selecting Add. See Figure 25.7, “DNS Server: Zone Editor (MX Records)”.

DNS Server: Zone Editor (MX Records)
Figure 25.7: DNS Server: Zone Editor (MX Records)
Zone Editor (SOA)

This page allows you to create SOA (start of authority) records. For an explanation of the individual options, refer to Example 25.6, “The /var/lib/named/example.com.zone File”. Changing SOA records is not supported for dynamic zones managed via LDAP.

DNS Server: Zone Editor (SOA)
Figure 25.8: DNS Server: Zone Editor (SOA)
Zone Editor (Records)

This dialog manages name resolution. In Record Key, enter the host name then select its type. The A type represents the main entry. The value for this should be an IP address (IPv4). Use AAAA for IPv6 addresses. CNAME is an alias. Use the types NS and MX for detailed or partial records that expand on the information provided in the NS Records and MX Records tabs. These three types resolve to an existing A record. PTR is for reverse zones. It is the opposite of an A record, for example:

hostname.example.com. IN A 192.168.0.1
1.0.168.192.in-addr.arpa IN PTR hostname.example.com.
25.3.2.9.1 Adding Reverse Zones

To add a reverse zone, follow this procedure:

  1. Start YaST › DNS Server › DNS Zones.

  2. If you have not added a master forward zone, add it and Edit it.

  3. In the Records tab, fill the corresponding Record Key and Value, then add the record with Add and confirm with OK. If YaST complains about a non-existing record for a name server, add it in the NS Records tab.

    Adding a Record for a Master Zone
    Figure 25.9: Adding a Record for a Master Zone
  4. Back in the DNS Zones window, add a reverse master zone.

    Adding a Reverse Zone
    Figure 25.10: Adding a Reverse Zone
  5. Edit the reverse zone, and in the Records tab, you can see the PTR: Reverse translation record type. Add the corresponding Record Key and Value, then click Add and confirm with OK.

    Adding a Reverse Record
    Figure 25.11: Adding a Reverse Record

    Add a name server record if needed.

Tip
Tip: Editing the Reverse Zone

After adding a forward zone, go back to the main menu and select the reverse zone for editing. There in the tab Basics activate the check box Automatically Generate Records From and select your forward zone. That way, all changes to the forward zone are automatically updated in the reverse zone.

25.4 Starting the BIND Name Server

On a SUSE® Linux Enterprise Server system, the name server BIND (Berkeley Internet Name Domain) comes preconfigured, so it can be started right after installation without any problems. Normally, if you already have an Internet connection and entered 127.0.0.1 as the name server address for localhost in /etc/resolv.conf, you already have a working name resolution without needing to know the DNS of the provider. BIND carries out name resolution via the root name server, a notably slower process. Normally, the DNS of the provider should be entered with its IP address in the configuration file /etc/named.conf under forwarders to ensure effective and secure name resolution. If this works so far, the name server runs as a pure caching-only name server. Only when you configure its own zones it becomes a proper DNS. Find a simple example documented in /usr/share/doc/packages/bind/config.

Tip
Tip: Automatic Adaptation of the Name Server Information

Depending on the type of Internet connection or the network connection, the name server information can automatically be adapted to the current conditions. To do this, set the NETCONFIG_DNS_POLICY variable in the /etc/sysconfig/network/config file to auto.

However, do not set up an official domain until one is assigned to you by the responsible institution. Even if you have your own domain and it is managed by the provider, you are better off not using it, because BIND would otherwise not forward requests for this domain. The Web server at the provider, for example, would not be accessible for this domain.

To start the name server, enter the command systemctl start named as root. Check with systemctl status named whether named (as the name server process is called) has been started successfully. Test the name server immediately on the local system with the host or dig programs, which should return localhost as the default server with the address 127.0.0.1. If this is not the case, /etc/resolv.conf probably contains an incorrect name server entry or the file does not exist. For the first test, enter host 127.0.0.1, which should always work. If you get an error message, use systemctl status named to see whether the server is actually running. If the name server does not start or behaves unexpectedly, check the output of journalctl -e.

To use the name server of the provider (or one already running on your network) as the forwarder, enter the corresponding IP address or addresses in the options section under forwarders. The addresses included in Example 25.1, “Forwarding Options in named.conf” are examples only. Adjust these entries to your own setup.

Example 25.1: Forwarding Options in named.conf
options {
        directory "/var/lib/named";
        forwarders { 10.11.12.13; 10.11.12.14; };
        listen-on { 127.0.0.1; 192.168.1.116; };
        allow-query { 127/8; 192.168/16 };
        notify no;
};

The options entry is followed by entries for the zone, localhost, and 0.0.127.in-addr.arpa. The type hint entry under . should always be present. The corresponding files do not need to be modified and should work as they are. Also make sure that each entry is closed with a ; and that the curly braces are in the correct places. After changing the configuration file /etc/named.conf or the zone files, tell BIND to reread them with systemctl reload named. Achieve the same by stopping and restarting the name server with systemctl restart named. Stop the server at any time by entering systemctl stop named.

25.5 The /etc/named.conf Configuration File

All the settings for the BIND name server itself are stored in the /etc/named.conf file. However, the zone data for the domains to handle (consisting of the host names, IP addresses, and so on) are stored in separate files in the /var/lib/named directory. The details of this are described later.

/etc/named.conf is roughly divided into two areas. One is the options section for general settings and the other consists of zone entries for the individual domains. A logging section and acl (access control list) entries are optional. Comment lines begin with a # sign or //. A minimal /etc/named.conf is shown in Example 25.2, “A Basic /etc/named.conf”.

Example 25.2: A Basic /etc/named.conf
options {
        directory "/var/lib/named";
        forwarders { 10.0.0.1; };
        notify no;
};

zone "localhost" in {
       type master;
       file "localhost.zone";
};

zone "0.0.127.in-addr.arpa" in {
        type master;
        file "127.0.0.zone";
};

zone "." in {
        type hint;
        file "root.hint";
};

25.5.1 Important Configuration Options

directory "FILENAME";

Specifies the directory in which BIND can find the files containing the zone data. Usually, this is /var/lib/named.

forwarders { IP-ADDRESS; };

Specifies the name servers (mostly of the provider) to which DNS requests should be forwarded if they cannot be resolved directly. Replace IP-ADDRESS with an IP address like 192.168.1.116.

forward first;

Causes DNS requests to be forwarded before an attempt is made to resolve them via the root name servers. Instead of forward first, forward only can be written to have all requests forwarded and none sent to the root name servers. This makes sense for firewall configurations.

listen-on port 53 { 127.0.0.1; IP-ADDRESS; };

Tells BIND on which network interfaces and port to accept client queries. port 53 does not need to be specified explicitly, because 53 is the default port. Enter 127.0.0.1 to permit requests from the local host. If you omit this entry entirely, all interfaces are used by default.

listen-on-v6 port 53 {any; };

Tells BIND on which port it should listen for IPv6 client requests. The only alternative to any is none. As far as IPv6 is concerned, the server only accepts wild card addresses.

query-source address * port 53;

This entry is necessary if a firewall is blocking outgoing DNS requests. This tells BIND to post requests externally from port 53 and not from any of the high ports above 1024.

query-source-v6 address * port 53;

Tells BIND which port to use for IPv6 queries.

allow-query { 127.0.0.1; NET; };

Defines the networks from which clients can post DNS requests. Replace NET with address information like 192.168.2.0/24. The /24 at the end is an abbreviated expression for the netmask (in this case 255.255.255.0).

allow-transfer ! *;;

Controls which hosts can request zone transfers. In the example, such requests are completely denied with ! *. Without this entry, zone transfers can be requested from anywhere without restrictions.

statistics-interval 0;

In the absence of this entry, BIND generates several lines of statistical information per hour in the system's journal. Set it to 0 to suppress these statistics completely or set an interval in minutes.

cleaning-interval 720;

This option defines at which time intervals BIND clears its cache. This triggers an entry in the system's journal each time it occurs. The time specification is in minutes. The default is 60 minutes.

interface-interval 0;

BIND regularly searches the network interfaces for new or nonexistent interfaces. If this value is set to 0, this is not done and BIND only listens at the interfaces detected at start-up. Otherwise, the interval can be defined in minutes. The default is sixty minutes.

notify no;

no prevents other name servers from being informed when changes are made to the zone data or when the name server is restarted.

For a list of available options, read the manual page man 5 named.conf.

25.5.2 Logging

What, how, and where logging takes place can be extensively configured in BIND. Normally, the default settings should be sufficient. Example 25.3, “Entry to Disable Logging”, shows the simplest form of such an entry and completely suppresses any logging.

Example 25.3: Entry to Disable Logging
logging {
        category default { null; };
};

25.5.3 Zone Entries

Example 25.4: Zone Entry for example.com
zone "example.com" in {
      type master;
      file "example.com.zone";
      notify no;
};

After zone, specify the name of the domain to administer (example.com) followed by in and a block of relevant options enclosed in curly braces, as shown in Example 25.4, “Zone Entry for example.com”. To define a slave zone, switch the type to slave and specify a name server that administers this zone as master (which, in turn, may be a slave of another master), as shown in Example 25.5, “Zone Entry for example.net”.

Example 25.5: Zone Entry for example.net
zone "example.net" in {
      type slave;
      file "slave/example.net.zone";
      masters { 10.0.0.1; }; 
};

The zone options:

type master;

By specifying master, tell BIND that the zone is handled by the local name server. This assumes that a zone file has been created in the correct format.

type slave;

This zone is transferred from another name server. It must be used together with masters.

type hint;

The zone . of the hint type is used to set the root name servers. This zone definition can be left as is.

file example.com.zone or file slave/example.net.zone;

This entry specifies the file where zone data for the domain is located. This file is not required for a slave, because this data is pulled from another name server. To differentiate master and slave files, use the directory slave for the slave files.

masters { SERVER_IP_ADDRESS; };

This entry is only needed for slave zones. It specifies from which name server the zone file should be transferred.

allow-update {! *; };

This option controls external write access, which would allow clients to make a DNS entry—something not normally desirable for security reasons. Without this entry, zone updates are not allowed. The above entry achieves the same because ! * effectively bans any such activity.

25.6 Zone Files

Two types of zone files are needed. One assigns IP addresses to host names and the other does the reverse: it supplies a host name for an IP address.

Tip
Tip: Using the Dot (Period, Fullstop) in Zone Files

The "." has an important meaning in the zone files. If host names are given without a final dot (.), the zone is appended. Complete host names specified with a full domain name must end with a dot (.) to avoid having the domain added to it again. A missing or wrongly placed "." is probably the most frequent cause of name server configuration errors.

The first case to consider is the zone file example.com.zone, responsible for the domain example.com, shown in Example 25.6, “The /var/lib/named/example.com.zone File”.

Example 25.6: The /var/lib/named/example.com.zone File
1.  $TTL 2D
2.  example.com. IN SOA      dns  root.example.com. ( 
3.               2003072441  ; serial
4.               1D          ; refresh
5.               2H          ; retry
6.               1W          ; expiry
7.               2D )        ; minimum
8.
9.               IN NS       dns 
10.              IN MX       10 mail
11.
12. gate         IN A        192.168.5.1 
13.              IN A        10.0.0.1 
14. dns          IN A        192.168.1.116 
15. mail         IN A        192.168.3.108 
16. jupiter      IN A        192.168.2.100
17. venus        IN A        192.168.2.101
18. saturn       IN A        192.168.2.102
19. mercury      IN A        192.168.2.103
20. ntp          IN CNAME    dns 
21. dns6         IN A6  0    2002:c0a8:174::
Line 1:

$TTL defines the default time to live that should apply to all the entries in this file. In this example, entries are valid for a period of two days (2 D).

Line 2:

This is where the SOA (start of authority) control record begins:

  • The name of the domain to administer is example.com in the first position. This ends with ".", because otherwise the zone would be appended a second time. Alternatively, @ can be entered here, in which case the zone would be extracted from the corresponding entry in /etc/named.conf.

  • After IN SOA is the name of the name server in charge as master for this zone. The name is expanded from dns to dns.example.com, because it does not end with a ".".

  • An e-mail address of the person in charge of this name server follows. Because the @ sign already has a special meaning, "." is entered here instead. For root@example.com the entry must read root.example.com.. The "." must be included at the end to prevent the zone from being added.

  • The ( includes all lines up to ) into the SOA record.

Line 3:

The serial number is an arbitrary number that is increased each time this file is changed. It is needed to inform the secondary name servers (slave servers) of changes. For this, a 10 digit number of the date and run number, written as YYYYMMDDNN, has become the customary format.

Line 4:

The refresh rate specifies the time interval at which the secondary name servers verify the zone serial number. In this case, one day.

Line 5:

The retry rate specifies the time interval at which a secondary name server, in case of error, attempts to contact the primary server again. Here, two hours.

Line 6:

The expiration time specifies the time frame after which a secondary name server discards the cached data if it has not regained contact to the primary server. Here, a week.

Line 7:

The last entry in the SOA record specifies the negative caching TTL—the time for which results of unresolved DNS queries from other servers may be cached.

Line 9:

The IN NS specifies the name server responsible for this domain. dns is extended to dns.example.com because it does not end with a ".". There can be several lines like this—one for the primary and one for each secondary name server. If notify is not set to no in /etc/named.conf, all the name servers listed here are informed of the changes made to the zone data.

Line 10:

The MX record specifies the mail server that accepts, processes, and forwards e-mails for the domain example.com. In this example, this is the host mail.example.com. The number in front of the host name is the preference value. If there are multiple MX entries, the mail server with the smallest value is taken first. If mail delivery to this server fails, the next entry with higher value is used.

Lines 12–19:

These are the actual address records where one or more IP addresses are assigned to host names. The names are listed here without a "." because they do not include their domain, so example.com is added to all of them. Two IP addresses are assigned to the host gate, as it has two network cards. Wherever the host address is a traditional one (IPv4), the record is marked with A. If the address is an IPv6 address, the entry is marked with AAAA.

Note
Note: IPv6 Syntax

The IPv6 record has a slightly different syntax than IPv4. Because of the fragmentation possibility, it is necessary to provide information about missed bits before the address. To fill up the IPv6 address with the needed number of 0, add two colons at the correct place in the address.

pluto     AAAA 2345:00C1:CA11::1234:5678:9ABC:DEF0
pluto     AAAA 2345:00D2:DA11::1234:5678:9ABC:DEF0
Line 20:

The alias ntp can be used to address dns (CNAME means canonical name).

The pseudo domain in-addr.arpa is used for the reverse lookup of IP addresses into host names. It is appended to the network part of the address in reverse notation. So 192.168 is resolved into 168.192.in-addr.arpa. See Example 25.7, “Reverse Lookup”.

Example 25.7: Reverse Lookup
1.  $TTL 2D
2.  168.192.in-addr.arpa.   IN SOA dns.example.com. root.example.com. (
3.                          2003072441      ; serial
4.                          1D              ; refresh
5.                          2H              ; retry
6.                          1W              ; expiry
7.                          2D )            ; minimum
8.
9.                          IN NS           dns.example.com.
10.
11. 1.5                     IN PTR          gate.example.com. 
12. 100.3                   IN PTR          www.example.com. 
13. 253.2                   IN PTR          cups.example.com.
Line 1:

$TTL defines the standard TTL that applies to all entries here.

Line 2:

The configuration file should activate reverse lookup for the network 192.168. Given that the zone is called 168.192.in-addr.arpa, it should not be added to the host names. Therefore, all host names are entered in their complete form—with their domain and with a "." at the end. The remaining entries correspond to those described for the previous example.com example.

Lines 3–7:

See the previous example for example.com.

Line 9:

Again this line specifies the name server responsible for this zone. This time, however, the name is entered in its complete form with the domain and a "." at the end.

Lines 11–13:

These are the pointer records hinting at the IP addresses on the respective hosts. Only the last part of the IP address is entered at the beginning of the line, without the "." at the end. Appending the zone to this (without the .in-addr.arpa) results in the complete IP address in reverse order.

Normally, zone transfers between different versions of BIND should be possible without any problems.

25.7 Dynamic Update of Zone Data

The term dynamic update refers to operations by which entries in the zone files of a master server are added, changed, or deleted. This mechanism is described in RFC 2136. Dynamic update is configured individually for each zone entry by adding an optional allow-update or update-policy rule. Zones to update dynamically should not be edited by hand.

Transmit the entries to update to the server with the command nsupdate. For the exact syntax of this command, check the manual page for nsupdate (man 8 nsupdate). For security reasons, any such update should be performed using TSIG keys as described in Section 25.8, “Secure Transactions”.

25.8 Secure Transactions

Secure transactions can be made with transaction signatures (TSIGs) based on shared secret keys (also called TSIG keys). This section describes how to generate and use such keys.

Secure transactions are needed for communication between different servers and for the dynamic update of zone data. Making the access control dependent on keys is much more secure than merely relying on IP addresses.

Generate a TSIG key with the following command (for details, see man dnssec-keygen):

dnssec-keygen -a hmac-md5 -b 128 -n HOST host1-host2

This creates two files with names similar to these:

Khost1-host2.+157+34265.private Khost1-host2.+157+34265.key

The key itself (a string like ejIkuCyyGJwwuN3xAteKgg==) is found in both files. To use it for transactions, the second file (Khost1-host2.+157+34265.key) must be transferred to the remote host, preferably in a secure way (using scp, for example). On the remote server, the key must be included in the /etc/named.conf file to enable a secure communication between host1 and host2:

key host1-host2 {
 algorithm hmac-md5;
 secret "ejIkuCyyGJwwuN3xAteKgg==";
};
Warning
Warning: File Permissions of /etc/named.conf

Make sure that the permissions of /etc/named.conf are properly restricted. The default for this file is 0640, with the owner being root and the group named. As an alternative, move the keys to an extra file with specially limited permissions, which is then included from /etc/named.conf. To include an external file, use:

include  "filename"

Replace filename with an absolute path to your file with keys.

To enable the server host1 to use the key for host2 (which has the address 10.1.2.3 in this example), the server's /etc/named.conf must include the following rule:

server 10.1.2.3 {
  keys { host1-host2. ;};
};

Analogous entries must be included in the configuration files of host2.

Add TSIG keys for any ACLs (access control lists, not to be confused with file system ACLs) that are defined for IP addresses and address ranges to enable transaction security. The corresponding entry could look like this:

allow-update { key host1-host2. ;};

This topic is discussed in more detail in the BIND Administrator Reference Manual under update-policy.

25.9 DNS Security

DNSSEC, or DNS security, is described in RFC 2535. The tools available for DNSSEC are discussed in the BIND Manual.

A zone considered secure must have one or several zone keys associated with it. These are generated with dnssec-keygen, as are the host keys. The DSA encryption algorithm is currently used to generate these keys. The public keys generated should be included in the corresponding zone file with an $INCLUDE rule.

With the command dnssec-signzone, you can create sets of generated keys (keyset- files), transfer them to the parent zone in a secure manner, and sign them. This generates the files to include for each zone in /etc/named.conf.

25.10 For More Information

For more information, see the BIND Administrator Reference Manual from the bind-doc package, which is installed under /usr/share/doc/packages/bind/arm. Consider additionally consulting the RFCs referenced by the manual and the manual pages included with BIND. /usr/share/doc/packages/bind/README.SUSE contains up-to-date information about BIND in SUSE Linux Enterprise Server.

26 DHCP

  • Filename: net_dhcp.xml
  • ID: cha.dhcp
Abstract

The purpose of the Dynamic Host Configuration Protocol (DHCP) is to assign network settings centrally (from a server) rather than configuring them locally on every workstation. A host configured to use DHCP does not have control over its own static address. It is enabled to configure itself completely and automatically according to directions from the server. If you use the NetworkManager on the client side, you do not need to configure the client. This is useful if you have changing environments and only one interface active at a time. Never use NetworkManager on a machine that runs a DHCP server.

Tip
Tip: IBM z Systems: DHCP Support

On IBM z Systems platforms, DHCP only works on interfaces using the OSA and OSA Express network cards. These cards are the only ones with a MAC, which is required for the DHCP autoconfiguration features.

One way to configure a DHCP server is to identify each client using the hardware address of its network card (which should be fixed in most cases), then supply that client with identical settings each time it connects to the server. DHCP can also be configured to assign addresses to each relevant client dynamically from an address pool set up for this purpose. In the latter case, the DHCP server tries to assign the same address to the client each time it receives a request, even over extended periods. This works only if the network does not have more clients than addresses.

DHCP makes life easier for system administrators. Any changes, even bigger ones, related to addresses and the network configuration in general can be implemented centrally by editing the server's configuration file. This is much more convenient than reconfiguring numerous workstations. It is also much easier to integrate machines, particularly new machines, into the network, because they can be given an IP address from the pool. Retrieving the appropriate network settings from a DHCP server is especially useful in case of laptops regularly used in different networks.

In this chapter, the DHCP server will run in the same subnet as the workstations, 192.168.2.0/24 with 192.168.2.1 as gateway. It has the fixed IP address 192.168.2.254 and serves two address ranges, 192.168.2.10 to 192.168.2.20 and 192.168.2.100 to 192.168.2.200.

A DHCP server supplies not only the IP address and the netmask, but also the host name, domain name, gateway, and name server addresses for the client to use. In addition to that, DHCP allows several other parameters to be configured in a centralized way, for example, a time server from which clients may poll the current time or even a print server.

26.1 Configuring a DHCP Server with YaST

To install a DHCP server, start YaST and select Software › Software Management. Choose Filter › Patterns and select DHCP and DNS Server. Confirm the installation of the dependent packages to finish the installation process.

Important
Important: LDAP Support

The YaST DHCP module can be set up to store the server configuration locally (on the host that runs the DHCP server) or to have its configuration data managed by an LDAP server. To use LDAP, set up your LDAP environment before configuring the DHCP server.

For more information about LDAP, see Chapter 5, LDAP—A Directory Service.

The YaST DHCP module (yast2-dhcp-server) allows you to set up your own DHCP server for the local network. The module can run in wizard mode or expert configuration mode.

26.1.1 Initial Configuration (Wizard)

When the module is started for the first time, a wizard starts, prompting you to make a few basic decisions concerning server administration. Completing this initial setup produces a very basic server configuration that should function in its essential aspects. The expert mode can be used to deal with more advanced configuration tasks. Proceed as follows:

  1. Select the interface from the list to which the DHCP server should listen and click Select. After this, select Open Firewall for Selected Interfaces to open the firewall for this interface, and click Next. See Figure 26.1, “DHCP Server: Card Selection”.

    DHCP Server: Card Selection
    Figure 26.1: DHCP Server: Card Selection
  2. Use the check box to determine whether your DHCP settings should be automatically stored by an LDAP server. In the text boxes, provide the network specifics for all clients the DHCP server should manage. These specifics are the domain name, address of a time server, addresses of the primary and secondary name server, addresses of a print and a WINS server (for a mixed network with both Windows and Linux clients), gateway address, and lease time. See Figure 26.2, “DHCP Server: Global Settings”.

    DHCP Server: Global Settings
    Figure 26.2: DHCP Server: Global Settings
  3. Configure how dynamic IP addresses should be assigned to clients. To do so, specify an IP range from which the server can assign addresses to DHCP clients. All these addresses must be covered by the same netmask. Also specify the lease time during which a client may keep its IP address without needing to request an extension of the lease. Optionally, specify the maximum lease time—the period during which the server reserves an IP address for a particular client. See Figure 26.3, “DHCP Server: Dynamic DHCP”.

    DHCP Server: Dynamic DHCP
    Figure 26.3: DHCP Server: Dynamic DHCP
  4. Define how the DHCP server should be started. Specify whether to start the DHCP server automatically when the system is booted or manually when needed (for example, for testing purposes). Click Finish to complete the configuration of the server. See Figure 26.4, “DHCP Server: Start-Up”.

    DHCP Server: Start-Up
    Figure 26.4: DHCP Server: Start-Up
  5. Instead of using dynamic DHCP in the way described in the preceding steps, you can also configure the server to assign addresses in quasi-static fashion. Use the text boxes provided in the lower part to specify a list of the clients to manage in this way. Specifically, provide the Name and the IP Address to give to such a client, the Hardware Address, and the Network Type (token ring or Ethernet). Modify the list of clients, which is shown in the upper part with Add, Edit, and Delete from List. See Figure 26.5, “DHCP Server: Host Management”.

    DHCP Server: Host Management
    Figure 26.5: DHCP Server: Host Management

26.1.2 DHCP Server Configuration (Expert)

In addition to the configuration method discussed earlier, there is also an expert configuration mode that allows you to change the DHCP server setup in every detail. Start the expert configuration by clicking DHCP Server Expert Configuration in the Start-Up dialog (see Figure 26.4, “DHCP Server: Start-Up”).

Chroot Environment and Declarations

In this first dialog, make the existing configuration editable by selecting Start DHCP Server. An important feature of the behavior of the DHCP server is its ability to run in a chroot environment, or chroot jail, to secure the server host. If the DHCP server should ever be compromised by an outside attack, the attacker will still be in the chroot jail, which prevents him from accessing the rest of the system. The lower part of the dialog displays a tree view with the declarations that have already been defined. Modify these with Add, Delete, and Edit. Selecting Advanced takes you to additional expert dialogs. See Figure 26.6, “DHCP Server: Chroot Jail and Declarations”. After selecting Add, define the type of declaration to add. With Advanced, view the log file of the server, configure TSIG key management, and adjust the configuration of the firewall according to the setup of the DHCP server.

DHCP Server: Chroot Jail and Declarations
Figure 26.6: DHCP Server: Chroot Jail and Declarations
Selecting the Declaration Type

The Global Options of the DHCP server are made up of several declarations. This dialog lets you set the declaration types Subnet, Host, Shared Network, Group, Pool of Addresses, and Class. This example shows the selection of a new subnet (see Figure 26.7, “DHCP Server: Selecting a Declaration Type”).

DHCP Server: Selecting a Declaration Type
Figure 26.7: DHCP Server: Selecting a Declaration Type
Subnet Configuration

This dialog allows you specify a new subnet with its IP address and netmask. In the middle part of the dialog, modify the DHCP server start options for the selected subnet using Add, Edit, and Delete. To set up dynamic DNS for the subnet, select Dynamic DNS.

DHCP Server: Configuring Subnets
Figure 26.8: DHCP Server: Configuring Subnets
TSIG Key Management

If you chose to configure dynamic DNS in the previous dialog, you can now configure the key management for a secure zone transfer. Selecting OK takes you to another dialog in which to configure the interface for dynamic DNS (see Figure 26.10, “DHCP Server: Interface Configuration for Dynamic DNS”).

DHCP Server: TSIG Configuration
Figure 26.9: DHCP Server: TSIG Configuration
Dynamic DNS: Interface Configuration

You can now activate dynamic DNS for the subnet by selecting Enable Dynamic DNS for This Subnet. After doing so, use the drop-down box to activate the TSIG keys for forward and reverse zones, making sure that the keys are the same for the DNS and the DHCP server. With Update Global Dynamic DNS Settings, enable the automatic update and adjustment of the global DHCP server settings according to the dynamic DNS environment. Finally, define which forward and reverse zones should be updated per dynamic DNS, specifying the name of the primary name server for each of the two zones. Selecting OK returns to the subnet configuration dialog (see Figure 26.8, “DHCP Server: Configuring Subnets”). Selecting OK again returns to the original expert configuration dialog.

DHCP Server: Interface Configuration for Dynamic DNS
Figure 26.10: DHCP Server: Interface Configuration for Dynamic DNS
Network Interface Configuration

To define the interfaces the DHCP server should listen to and to adjust the firewall configuration, select Advanced › Interface Configuration from the expert configuration dialog. From the list of interfaces displayed, select one or more that should be attended by the DHCP server. If clients in all subnets need to be able to communicate with the server and the server host also runs a firewall, adjust the firewall accordingly. To do so, select Adapt Firewall Settings. YaST then adjusts the rules of SuSEFirewall2 to the new conditions (see Figure 26.11, “DHCP Server: Network Interface and Firewall”), after which you can return to the original dialog by selecting OK.

DHCP Server: Network Interface and Firewall
Figure 26.11: DHCP Server: Network Interface and Firewall

After completing all configuration steps, close the dialog with OK. The server is now started with its new configuration.

26.2 DHCP Software Packages

Both the DHCP server and the DHCP clients are available for SUSE Linux Enterprise Server. The DHCP server available is dhcpd (published by the Internet Systems Consortium). On the client side, there is dhcp-client (also from ISC) and tools coming with the wicked package.

By default, the wicked tools are installed with the services wickedd-dhcp4 and wickedd-dhcp6. Both are launched automatically on each system boot to watch for a DHCP server. They do not need a configuration file to do their job and work out of the box in most standard setups. For more complex situations, use the ISC dhcp-client, which is controlled by means of the configuration files /etc/dhclient.conf and /etc/dhclient6.conf.

26.3 The DHCP Server dhcpd

The core of any DHCP system is the dynamic host configuration protocol daemon. This server leases addresses and watches how they are used, according to the settings defined in the configuration file /etc/dhcpd.conf. By changing the parameters and values in this file, a system administrator can influence the program's behavior in numerous ways. Look at the basic sample /etc/dhcpd.conf file in Example 26.1, “The Configuration File /etc/dhcpd.conf”.

Example 26.1: The Configuration File /etc/dhcpd.conf
default-lease-time 600;         # 10 minutes
max-lease-time 7200;            # 2  hours

option domain-name "example.com";
option domain-name-servers 192.168.1.116;
option broadcast-address 192.168.2.255;
option routers 192.168.2.1;
option subnet-mask 255.255.255.0;

subnet 192.168.2.0 netmask 255.255.255.0
 {
  range 192.168.2.10 192.168.2.20;
  range 192.168.2.100 192.168.2.200;
 }

This simple configuration file should be sufficient to get the DHCP server to assign IP addresses in the network. Make sure that a semicolon is inserted at the end of each line, because otherwise dhcpd is not started.

The sample file can be divided into three sections. The first one defines how many seconds an IP address is leased to a requesting client by default (default-lease-time) before it should apply for renewal. This section also includes a statement of the maximum period for which a machine may keep an IP address assigned by the DHCP server without applying for renewal (max-lease-time).

In the second part, some basic network parameters are defined on a global level:

  • The line option domain-name defines the default domain of your network.

  • With the entry option domain-name-servers, specify up to three values for the DNS servers used to resolve IP addresses into host names and vice versa. Ideally, configure a name server on your machine or somewhere else in your network before setting up DHCP. That name server should also define a host name for each dynamic address and vice versa. To learn how to configure your own name server, read Chapter 25, The Domain Name System.

  • The line option broadcast-address defines the broadcast address the requesting client should use.

  • With option routers, set where the server should send data packets that cannot be delivered to a host on the local network (according to the source and target host address and the subnet mask provided). Usually, especially in smaller networks, this router is identical to the Internet gateway.

  • With option subnet-mask, specify the netmask assigned to clients.

The last section of the file defines a network, including a subnet mask. To finish, specify the address range that the DHCP daemon should use to assign IP addresses to interested clients. In Example 26.1, “The Configuration File /etc/dhcpd.conf”, clients may be given any address between 192.168.2.10 and 192.168.2.20 or 192.168.2.100 and 192.168.2.200.

After editing these few lines, you should be able to activate the DHCP daemon with the command systemctl start dhcpd. It will be ready for use immediately. Use the command rcdhcpd check-syntax to perform a brief syntax check. If you encounter any unexpected problems with your configuration (the server aborts with an error or does not return done on start), you should be able to find out what has gone wrong by looking for information either in the main system log that can be queried with the command journalctl (see Chapter 15, journalctl: Query the systemd Journal for more information).

On a default SUSE Linux Enterprise Server system, the DHCP daemon is started in a chroot environment for security reasons. The configuration files must be copied to the chroot environment so the daemon can find them. Normally, there is no need to worry about this because the command systemctl start dhcpd automatically copies the files.

26.3.1 Clients with Fixed IP Addresses

DHCP can also be used to assign a predefined, static address to a specific client. Addresses assigned explicitly always take priority over dynamic addresses from the pool. A static address never expires in the way a dynamic address would, for example, if there were not enough addresses available and the server needed to redistribute them among clients.

To identify a client configured with a static address, dhcpd uses the hardware address (which is a globally unique, fixed numerical code consisting of six octet pairs) for the identification of all network devices (for example, 00:30:6E:08:EC:80). If the respective lines, like the ones in Example 26.2, “Additions to the Configuration File”, are added to the configuration file of Example 26.1, “The Configuration File /etc/dhcpd.conf”, the DHCP daemon always assigns the same set of data to the corresponding client.

Example 26.2: Additions to the Configuration File
host jupiter {
hardware ethernet 00:30:6E:08:EC:80;
fixed-address 192.168.2.100;
}

The name of the respective client (host HOSTNAME, here jupiter) is entered in the first line and the MAC address in the second line. On Linux hosts, find the MAC address with the command ip link show followed by the network device (for example, eth0). The output should contain something like

link/ether 00:30:6E:08:EC:80

In the preceding example, a client with a network card having the MAC address 00:30:6E:08:EC:80 is assigned the IP address 192.168.2.100 and the host name jupiter automatically. The type of hardware to enter is ethernet in nearly all cases, although token-ring, which is often found on IBM systems, is also supported.

26.3.2 The SUSE Linux Enterprise Server Version

To improve security, the SUSE Linux Enterprise Server version of the ISC's DHCP server comes with the non-root/chroot patch by Ari Edelkind applied. This enables dhcpd to run with the user ID nobody and run in a chroot environment (/var/lib/dhcp). To make this possible, the configuration file dhcpd.conf must be located in /var/lib/dhcp/etc. The init script automatically copies the file to this directory when starting.

Control the server's behavior regarding this feature by means of entries in the file /etc/sysconfig/dhcpd. To run dhcpd without the chroot environment, set the variable DHCPD_RUN_CHROOTED in /etc/sysconfig/dhcpd to no.

To enable dhcpd to resolve host names even from within the chroot environment, some other configuration files must be copied as well:

  • /etc/localtime

  • /etc/host.conf

  • /etc/hosts

  • /etc/resolv.conf

These files are copied to /var/lib/dhcp/etc/ when starting the init script. Take these copies into account for any changes that they require if they are dynamically modified by scripts like /etc/ppp/ip-up. However, there should be no need to worry about this if the configuration file only specifies IP addresses (instead of host names).

If your configuration includes additional files that should be copied into the chroot environment, set these under the variable DHCPD_CONF_INCLUDE_FILES in the file /etc/sysconfig/dhcpd. To ensure that the DHCP logging facility keeps working even after a restart of the syslog daemon, there is an additional entry SYSLOGD_ADDITIONAL_SOCKET_DHCP in the file /etc/sysconfig/syslog.

26.4 For More Information

More information about DHCP is available at the Web site of the Internet Systems Consortium (http://www.isc.org/products/DHCP/). Information is also available in the dhcpd, dhcpd.conf, dhcpd.leases, and dhcp-options man pages.

27 Sharing File Systems with NFS

  • Filename: net_nfs.xml
  • ID: cha.nfs
Abstract

Distributing and sharing file systems over a network is a common task in corporate environments. The well-proven network file system (NFS) works with NIS, the yellow pages protocol. For a more secure protocol that works with LDAP and Kerberos, check NFSv4 (default). Combined with pNFS, you can eliminate performance bottlenecks.

NFS with NIS makes a network transparent to the user. With NFS, it is possible to distribute arbitrary file systems over the network. With an appropriate setup, users always find themselves in the same environment regardless of the terminal they currently use.

Important
Important: Need for DNS

In principle, all exports can be made using IP addresses only. To avoid time-outs, you need a working DNS system. DNS is necessary at least for logging purposes, because the mountd daemon does reverse lookups.

27.1 Terminology

The following are terms used in the YaST module.

Exports

A directory exported by an NFS server, which clients can integrate it into their system.

NFS Client

The NFS client is a system that uses NFS services from an NFS server over the Network File System protocol. The TCP/IP protocol is already integrated into the Linux kernel; there is no need to install any additional software.

NFS Server

The NFS server provides NFS services to clients. A running server depends on the following daemons: nfsd (worker), idmapd (ID-to-name mapping for NFSv4, needed for certain scenarios only), statd (file locking), and mountd (mount requests).

NFSv3

NFSv3 is the version 3 implementation, the old stateless NFS that supports client authentication.

NFSv4

NFSv4 is the new version 4 implementation that supports secure user authentication via kerberos. NFSv4 requires one single port only and thus is better suited for environments behind a firewall than NFSv3.

The protocol is specified as http://tools.ietf.org/html/rfc3530.

pNFS

Parallel NFS, a protocol extension of NFSv4. Any pNFS clients can directly access the data on an NFS server.

27.2 Installing NFS Server

The NFS server is not part of the default installation. To install the NFS server using YaST, choose Software › Software Management, select Patterns, and enable the File Server option in the Server Functions section. Press Accept to install the required packages.

Like NIS, NFS is a client/server system. However, a machine can be both—it can supply file systems over the network (export) and mount file systems from other hosts (import).

Note
Note: Mounting NFS Volumes Locally on the Exporting Server

Mounting NFS volumes locally on the exporting server is not supported on SUSE Linux Enterprise Server.

27.3 Configuring NFS Server

Configuring an NFS server can be done either through YaST or manually. For authentication, NFS can also be combined with Kerberos.

27.3.1 Exporting File Systems with YaST

With YaST, turn a host in your network into an NFS server—a server that exports directories and files to all hosts granted access to it or to all members of a group. Thus, the server can also provide applications without installing the applications locally on every host.

To set up such a server, proceed as follows:

Procedure 27.1: Setting Up an NFS Server
  1. Start YaST and select Network Services › NFS Server; see Figure 27.1, “NFS Server Configuration Tool”. You may be prompted to install additional software.

    NFS Server Configuration Tool
    Figure 27.1: NFS Server Configuration Tool
  2. Activate the Start radio button.

  3. If a firewall is active on your system (SuSEFirewall2), check Open Ports in Firewall. YaST adapts its configuration for the NFS server by enabling the nfs service.

  4. Check whether you want to Enable NFSv4. If you deactivate NFSv4, YaST will only support NFSv3. For information about enabling NFSv2, see Note: NFSv2.

    1. If NFSv4 is selected, additionally enter the appropriate NFSv4 domain name. This parameter is used by the idmapd daemon that is required for Kerberos setups or if clients cannot work with numeric user names. Leave it as localdomain (the default) if you do not run idmapd or do not have any special requirements. For more information on the idmapd daemon see /etc/idmapd.conf.

  5. Click Enable GSS Security if you need secure access to the server. A prerequisite for this is to have Kerberos installed on your domain and to have both the server and the clients kerberized. Click Next to proceed with the next configuration dialog.

  6. Click Add Directory in the upper half of the dialog to export your directory.

  7. If you have not configured the allowed hosts already, another dialog for entering the client information and options pops up automatically. Enter the host wild card (usually you can leave the default settings as they are).

    There are four possible types of host wild cards that can be set for each host: a single host (name or IP address), netgroups, wild cards (such as * indicating all machines can access the server), and IP networks.

    For more information about these options, see the exports man page.

  8. Click Finish to complete the configuration.

27.3.2 Exporting File Systems Manually

The configuration files for the NFS export service are /etc/exports and /etc/sysconfig/nfs. In addition to these files, /etc/idmapd.conf is needed for the NFSv4 server configuration with kerberized NFS or if the clients cannot work with numeric user names.

To start or restart the services, run the command systemctl restart nfsserver. This also restarts the RPC portmapper that is required by the NFS server.

To make sure the NFS server always starts at boot time, run sudo systemctl enable nfsserver.

Note
Note: NFSv4

NFSv4 is the latest version of NFS protocol available on SUSE Linux Enterprise Server. Configuring directories for export with NFSv4 is now the same as with NFSv3.

On SUSE Linux Enterprise Server 11, the bind mount in /etc/exports was mandatory. It is still supported, but now deprecated.

/etc/exports

The /etc/exports file contains a list of entries. Each entry indicates a directory that is shared and how it is shared. A typical entry in /etc/exports consists of:

/SHARED/DIRECTORY   HOST(OPTION_LIST)

For example:

/export/data   192.168.1.2(rw,sync)

Here the IP address 192.168.1.2 is used to identify the allowed client. You can also use the name of the host, a wild card indicating a set of hosts (*.abc.com, *, etc.), or netgroups (@my-hosts).

For a detailed explanation of all options and their meaning, refer to the man page of exports (man exports).

In case you have modified /etc/exports while the NFS server was running, you need to restart it for the changes to become active: sudo systemctl restart nfsserver.

/etc/sysconfig/nfs

The /etc/sysconfig/nfs file contains a few parameters that determine NFSv4 server daemon behavior. It is important to set the parameter NFS4_SUPPORT to yes (default). NFS4_SUPPORT determines whether the NFS server supports NFSv4 exports and clients.

In case you have modified /etc/sysconfig/nfs while the NFS server was running, you need to restart it for the changes to become active: sudo systemctl restart nfsserver.

Tip
Tip: Mount Options

On SUSE Linux Enterprise Server 11, the --bind mount in /etc/exports was mandatory. It is still supported, but now deprecated. Configuring directories for export with NFSv4 is now the same as with NFSv3.

Note
Note: NFSv2

If NFS clients still depend on NFSv2, enable it on the server in /etc/sysconfig/nfs by setting:

NFSD_OPTIONS="-V2"
MOUNTD_OPTIONS="-V2"

After restarting the service, check whether version 2 is available with the command:

tux > cat /proc/fs/nfsd/versions
+2 +3 +4 +4.1 -4.2
/etc/idmapd.conf

Starting with SLE 12 SP1, the idmapd daemon is only required if Kerberos authentication is used, or if clients cannot work with numeric user names. Linux clients can work with numeric user names since Linux kernel 2.6.39. The idmapd daemon does the name-to-ID mapping for NFSv4 requests to the server and replies to the client.

If required, idmapd needs to run on the NFSv4 server. Name-to-ID mapping on the client will be done by nfsidmap provided by the package nfs-client.

Make sure that there is a uniform way in which user names and IDs (uid) are assigned to users across machines that might probably be sharing file systems using NFS. This can be achieved by using NIS, LDAP, or any uniform domain authentication mechanism in your domain.

The parameter Domain must be set the same for both, client and server in the /etc/idmapd.conf file. If you are not sure, leave the domain as localdomain in the server and client files. A sample configuration file looks like the following:

[General]
Verbosity = 0
Pipefs-Directory = /var/lib/nfs/rpc_pipefs
Domain = localdomain

[Mapping]
Nobody-User = nobody
Nobody-Group = nobody

To start the idmapd daemon, run systemctl start nfs-idmapd. In case you have modified /etc/idmapd.conf while the daemon was running, you need to restart it for the changes to become active: systemctl start nfs-idmapd.

For more information, see the man pages of idmapd and idmapd.conf (man idmapd and man idmapd.conf).

27.3.3 NFS with Kerberos

To use Kerberos authentication for NFS, GSS security must be enabled. Select Enable GSS Security in the initial YaST NFS Server dialog. You must have a working Kerberos server to use this feature. YaST does not set up the server but only uses the provided functionality. If you want to use Kerberos authentication in addition to the YaST configuration, complete at least the following steps before running the NFS configuration:

  1. Make sure that both the server and the client are in the same Kerberos domain. They must access the same KDC (Key Distribution Center) server and share their krb5.keytab file (the default location on any machine is /etc/krb5.keytab). For more information about Kerberos, see Chapter 6, Network Authentication with Kerberos.

  2. Start the gssd service on the client with systemctl start rpc-gssd.service.

  3. Start the svcgssd service on the server with systemctl start rpc-svcgssd.service.

Kerberos authentication also requires the idmapd daemon to run on the server. For more information refer to /etc/idmapd.conf.

For more information about configuring kerberized NFS, refer to the links in Section 27.5, “For More Information”.

27.4 Configuring Clients

To configure your host as an NFS client, you do not need to install additional software. All needed packages are installed by default.

27.4.1 Importing File Systems with YaST

Authorized users can mount NFS directories from an NFS server into the local file tree using the YaST NFS client module. Proceed as follows:

Procedure 27.2: Importing NFS Directories
  1. Start the YaST NFS client module.

  2. Click Add in the NFS Shares tab. Enter the host name of the NFS server, the directory to import, and the mount point at which to mount this directory locally.

  3. When using NFSv4, select Enable NFSv4 in the NFS Settings tab. Additionally, the NFSv4 Domain Name must contain the same value as used by the NFSv4 server. The default domain is localdomain.

  4. To use Kerberos authentication for NFS, GSS security must be enabled. Select Enable GSS Security.

  5. Enable Open Port in Firewall in the NFS Settings tab if you use a Firewall and want to allow access to the service from remote computers. The firewall status is displayed next to the check box.

  6. Click OK to save your changes.

The configuration is written to /etc/fstab and the specified file systems are mounted. When you start the YaST configuration client at a later time, it also reads the existing configuration from this file.

Tip
Tip: NFS as a Root File System

On (diskless) systems, where the root partition is mounted via network as an NFS share, you need to be careful when configuring the network device with which the NFS share is accessible.

When shutting down or rebooting the system, the default processing order is to turn off network connections, then unmount the root partition. With NFS root, this order causes problems as the root partition cannot be cleanly unmounted as the network connection to the NFS share is already not activated. To prevent the system from deactivating the relevant network device, open the network device configuration tab as described in Section 16.4.1.2.5, “Activating the Network Device” and choose On NFSroot in the Device Activation pane.

27.4.2 Importing File Systems Manually

The prerequisite for importing file systems manually from an NFS server is a running RPC port mapper. The nfs service takes care to start it properly; thus, start it by entering systemctl start nfs as root. Then remote file systems can be mounted in the file system like local partitions using mount:

tux > sudo mount HOST:REMOTE-PATHLOCAL-PATH

To import user directories from the nfs.example.com machine, for example, use:

tux > sudo mount nfs.example.com:/home /home

27.4.2.1 Using the Automount Service

The autofs daemon can be used to mount remote file systems automatically. Add the following entry to the /etc/auto.master file:

/nfsmounts /etc/auto.nfs

Now the /nfsmounts directory acts as the root for all the NFS mounts on the client if the auto.nfs file is filled appropriately. The name auto.nfs is chosen for the sake of convenience—you can choose any name. In auto.nfs add entries for all the NFS mounts as follows:

localdata -fstype=nfs server1:/data
nfs4mount -fstype=nfs4 server2:/

Activate the settings with systemctl start autofs as root. In this example, /nfsmounts/localdata, the /data directory of server1, is mounted with NFS and /nfsmounts/nfs4mount from server2 is mounted with NFSv4.

If the /etc/auto.master file is edited while the service autofs is running, the automounter must be restarted for the changes to take effect with systemctl restart autofs.

27.4.2.2 Manually Editing /etc/fstab

A typical NFSv3 mount entry in /etc/fstab looks like this:

nfs.example.com:/data /local/path nfs rw,noauto 0 0

For NFSv4 mounts, use nfs4 instead of nfs in the third column:

nfs.example.com:/data /local/pathv4 nfs4 rw,noauto 0 0

The noauto option prevents the file system from being mounted automatically at start-up. If you want to mount the respective file system manually, it is possible to shorten the mount command specifying the mount point only:

tux > sudo mount /local/path
Note
Note: Mounting at Start-Up

If you do not enter the noauto option, the init scripts of the system will handle the mount of those file systems at start-up.

27.4.3 Parallel NFS (pNFS)

NFS is one of the oldest protocols, developed in the '80s. As such, NFS is usually sufficient if you want to share small files. However, when you want to transfer big files or large numbers of clients want to access data, an NFS server becomes a bottleneck and has a significant impact on the system performance. This is because of files quickly getting bigger, whereas the relative speed of your Ethernet has not fully kept up.

When you request a file from a regular NFS server, the server looks up the file metadata, collects all the data and transfers it over the network to your client. However, the performance bottleneck becomes apparent no matter how small or big the files are:

  • With small files most of the time is spent collecting the metadata.

  • With big files most of the time is spent on transferring the data from server to client.

pNFS, or parallel NFS, overcomes this limitation as it separates the file system metadata from the location of the data. As such, pNFS requires two types of servers:

  • A metadata or control server that handles all the non-data traffic

  • One or more storage server(s) that hold(s) the data

The metadata and the storage servers form a single, logical NFS server. When a client wants to read or write, the metadata server tells the NFSv4 client which storage server to use to access the file chunks. The client can access the data directly on the server.

SUSE Linux Enterprise Server supports pNFS on the client side only.

27.4.3.1 Configuring pNFS Client With YaST

Proceed as described in Procedure 27.2, “Importing NFS Directories”, but click the pNFS (v4.1) check box and optionally NFSv4 share. YaST will do all the necessary steps and will write all the required options in the file /etc/exports.

27.4.3.2 Configuring pNFS Client Manually

Refer to Section 27.4.2, “Importing File Systems Manually” to start. Most of the configuration is done by the NFSv4 server. For pNFS, the only difference is to add the minorversion option and the metadata server MDS_SERVER to your mount command:

tux > sudo mount -t nfs4 -o minorversion=1 MDS_SERVER MOUNTPOINT

To help with debugging, change the value in the /proc file system:

tux > sudo echo 32767 > /proc/sys/sunrpc/nfsd_debug
tux > sudo echo 32767 > /proc/sys/sunrpc/nfs_debug

27.5 For More Information

In addition to the man pages of exports, nfs, and mount, information about configuring an NFS server and client is available in /usr/share/doc/packages/nfsidmap/README. For further documentation online refer to the following Web sites:

28 Samba

  • Filename: net_samba.xml
  • ID: cha.samba
Abstract

Using Samba, a Unix machine can be configured as a file and print server for macOS, Windows, and OS/2 machines. Samba has developed into a fully-fledged and rather complex product. Configure Samba with YaST, or by editing the configuration file manually.

28.1 Terminology

The following are some terms used in Samba documentation and in the YaST module.

SMB protocol

Samba uses the SMB (server message block) protocol that is based on the NetBIOS services. Microsoft released the protocol so other software manufacturers could establish connections to a Microsoft domain network. With Samba, the SMB protocol works on top of the TCP/IP protocol, so the TCP/IP protocol must be installed on all clients.

Tip
Tip: IBM z Systems: NetBIOS Support

IBM z Systems merely supports SMB over TCP/IP. NetBIOS support is not available on these systems.

CIFS protocol

CIFS (common Internet file system) protocol is another protocol supported by Samba. CIFS defines a standard remote file system access protocol for use over the network, enabling groups of users to work together and share documents across the network.

NetBIOS

NetBIOS is a software interface (API) designed for communication between machines providing a name service. It enables machines connected to the network to reserve names for themselves. After reservation, these machines can be addressed by name. There is no central process that checks names. Any machine on the network can reserve as many names as it wants as long as the names are not already in use. The NetBIOS interface can be implemented for different network architectures. An implementation that works relatively closely with network hardware is called NetBEUI, but this is often called NetBIOS. Network protocols implemented with NetBIOS are IPX from Novell (NetBIOS via TCP/IP) and TCP/IP.

The NetBIOS names sent via TCP/IP have nothing in common with the names used in /etc/hosts or those defined by DNS. NetBIOS uses its own, completely independent naming convention. However, it is recommended to use names that correspond to DNS host names to make administration easier or use DNS natively. This is the default used by Samba.

Samba server

Samba server provides SMB/CIFS services and NetBIOS over IP naming services to clients. For Linux, there are three daemons for Samba server: smbd for SMB/CIFS services, nmbd for naming services, and winbind for authentication.

Samba client

The Samba client is a system that uses Samba services from a Samba server over the SMB protocol. Common operating systems, such as Windows and macOS support the SMB protocol. The TCP/IP protocol must be installed on all computers. Samba provides a client for the different Unix flavors. For Linux, there is a kernel module for SMB that allows the integration of SMB resources on the Linux system level. You do not need to run any daemon for the Samba client.

Shares

SMB servers provide resources to the clients by means of shares. Shares are printers and directories with their subdirectories on the server. It is exported by means of a name and can be accessed by its name. The share name can be set to any name—it does not need to be the name of the export directory. A printer is also assigned a name. Clients can access the printer by its name.

DC

A domain controller (DC) is a server that handles accounts in a domain. For data replication, additional domain controllers are available in one domain.

28.2 Installing a Samba Server

To install a Samba server, start YaST and select Software › Software Management. Choose View › Patterns and select File Server. Confirm the installation of the required packages to finish the installation process.

28.3 Starting and Stopping Samba

You can start or stop the Samba server automatically (during boot) or manually. Starting and stopping policy is a part of the YaST Samba server configuration described in Section 28.4.1, “Configuring a Samba Server with YaST”.

From a command line, stop services required for Samba with systemctl stop smb nmb and start them with systemctl start nmb smb. The smb service cares about winbind if needed.

Tip
Tip: winbind

winbind is an independent service, and as such is also offered as an individual samba-winbind package.

28.4 Configuring a Samba Server

A Samba server in SUSE® Linux Enterprise Server can be configured in two different ways: with YaST or manually. Manual configuration offers a higher level of detail, but lacks the convenience of the YaST GUI.

28.4.1 Configuring a Samba Server with YaST

To configure a Samba server, start YaST and select Network Services › Samba Server.

28.4.1.1 Initial Samba Configuration

When starting the module for the first time, the Samba Installation dialog starts, prompting you to make a few basic decisions concerning administration of the server. At the end of the configuration it prompts for the Samba administrator password (Samba Root Password). For later starts, the Samba Configuration dialog appears.

The Samba Installation dialog consists of two steps and optional detailed settings:

Workgroup or Domain Name

Select an existing name from Workgroup or Domain Name or enter a new one and click Next.

Samba Server Type

In the next step, specify whether your server should act as a primary domain controller (PDC), backup domain controller (BDC), or not act as a domain controller. Continue with Next.

If you do not want to proceed with a detailed server configuration, confirm with OK. Then in the final pop-up box, set the Samba root Password.

You can change all settings later in the Samba Configuration dialog with the Start-Up, Shares, Identity, Trusted Domains, and LDAP Settings tabs.

28.4.1.2 Advanced Samba Configuration

During the first start of the Samba server module the Samba Configuration dialog appears directly after the two initial steps described in Section 28.4.1.1, “Initial Samba Configuration”. Use it to adjust your Samba server configuration.

After editing your configuration, click OK to save your settings.

28.4.1.2.1 Starting the Server

In the Start Up tab, configure the start of the Samba server. To start the service every time your system boots, select During Boot. To activate manual start, choose Manually. More information about starting a Samba server is provided in Section 28.3, “Starting and Stopping Samba”.

In this tab, you can also open ports in your firewall. To do so, select Open Port in Firewall. If you have multiple network interfaces, select the network interface for Samba services by clicking Firewall Details, selecting the interfaces, and clicking OK.

28.4.1.2.2 Shares

In the Shares tab, determine the Samba shares to activate. There are some predefined shares, like homes and printers. Use Toggle Status to switch between Active and Inactive. Click Add to add new shares and Delete to delete the selected share.

Allow Users to Share Their Directories enables members of the group in Permitted Group to share directories they own with other users. For example, users for a local scope or DOMAIN\Users for a domain scope. The user also must make sure that the file system permissions allow access. With Maximum Number of Shares, limit the total amount of shares that may be created. To permit access to user shares without authentication, enable Allow Guest Access.

28.4.1.2.3 Identity

In the Identity tab, you can determine the domain with which the host is associated (Base Settings) and whether to use an alternative host name in the network (NetBIOS Hostname). It is also possible to use Microsoft Windows Internet Name Service (WINS) for name resolution. In this case, activate Use WINS for Hostname Resolution and decide whether to Retrieve WINS server via DHCP. To set expert global settings or set a user authentication source, for example LDAP instead of TDB database, click Advanced Settings.

28.4.1.2.4 Trusted Domains

To enable users from other domains to access your domain, make the appropriate settings in the Trusted Domains tab. To add a new domain, click Add. To remove the selected domain, click Delete.

28.4.1.2.5 LDAP Settings

In the tab LDAP Settings, you can determine the LDAP server to use for authentication. To test the connection to your LDAP server, click Test Connection. To set expert LDAP settings or use default values, click Advanced Settings.

For more information about LDAP configuration, see Chapter 5, LDAP—A Directory Service.

28.4.2 Configuring the Server Manually

If you intend to use Samba as a server, install samba. The main configuration file for Samba is /etc/samba/smb.conf. This file can be divided into two logical parts. The [global] section contains the central and global settings. The following default sections contain the individual file and printer shares:

  • [homes]

  • [profiles]

  • [users]

  • [groups]

  • [printers]

  • [print$]

Using this approach, options of the shares can be set differently or globally in the [global] section, which makes the configuration file easier to understand.

28.4.2.1 The global Section

The following parameters of the [global] section should be modified to match the requirements of your network setup, so other machines can access your Samba server via SMB in a Windows environment.

workgroup = WORKGROUP

This line assigns the Samba server to a workgroup. Replace WORKGROUP with an appropriate workgroup of your networking environment. Your Samba server appears under its DNS name unless this name has been assigned to some other machine in the network. If the DNS name is not available, set the server name using netbiosname=MYNAME. For more details about this parameter, see the smb.conf man page.

os level = 20

This parameter triggers whether your Samba server tries to become LMB (local master browser) for its workgroup. Choose a very low value such as 2 to spare the existing Windows network from any interruptions caused by a misconfigured Samba server. More information about this topic can be found in the Network Browsing chapter of the Samba 3 Howto; for more information on the Samba 3 Howto, see Section 28.9, “For More Information”.

If no other SMB server is in your network (such as a Windows 2000 server) and you want the Samba server to keep a list of all systems present in the local environment, set the os level to a higher value (for example, 65). Your Samba server is then chosen as LMB for your local network.

When changing this setting, consider carefully how this could affect an existing Windows network environment. First test the changes in an isolated network or at a noncritical time of day.

wins support and wins server

To integrate your Samba server into an existing Windows network with an active WINS server, enable the wins server option and set its value to the IP address of that WINS server.

If your Windows machines are connected to separate subnets and need to still be aware of each other, you have to set up a WINS server. To turn a Samba server into such a WINS server, set the option wins support = Yes. Make sure that only one Samba server of the network has this setting enabled. The options wins server and wins support must never be enabled at the same time in your smb.conf file.

28.4.2.2 Shares

The following examples illustrate how a CD-ROM drive and the user directories (homes) are made available to the SMB clients.

[cdrom]

To avoid having the CD-ROM drive accidentally made available, these lines are deactivated with comment marks (semicolons in this case). Remove the semicolons in the first column to share the CD-ROM drive with Samba.

Example 28.1: A CD-ROM Share
[cdrom]
       comment = Linux CD-ROM
       path = /media/cdrom
       locking = No
[cdrom] and comment

The [cdrom] section entry is the name of the share that can be seen by all SMB clients on the network. An additional comment can be added to further describe the share.

path = /media/cdrom

path exports the directory /media/cdrom.

By means of a very restrictive default configuration, this kind of share is only made available to the users present on this system. If this share should be made available to everybody, add a line guest ok = yes to the configuration. This setting gives read permissions to anyone on the network. It is recommended to handle this parameter with great care. This applies even more to the use of this parameter in the [global] section.

[homes]

The [homes] share is of special importance here. If the user has a valid account and password for the Linux file server and his own home directory, he can be connected to it.

Example 28.2: [homes] Share
[homes]
        comment = Home Directories
        valid users = %S
        browseable = No
        read only = No
        inherit acls = Yes
[homes]

As long as there is no other share using the share name of the user connecting to the SMB server, a share is dynamically generated using the [homes] share directives. The resulting name of the share is the user name.

valid users = %S

%S is replaced with the concrete name of the share when a connection has been successfully established. For a [homes] share, this is always the user name. As a consequence, access rights to a user's share are restricted exclusively to that user.

browseable = No

This setting makes the share invisible in the network environment.

read only = No

By default, Samba prohibits write access to any exported share by means of the read only = Yes parameter. To make a share writable, set the value read only = No, which is synonymous with writable = Yes.

create mask = 0640

Systems that are not based on MS Windows NT do not understand the concept of Unix permissions, so they cannot assign permissions when creating a file. The parameter create mask defines the access permissions assigned to newly created files. This only applies to writable shares. In effect, this setting means the owner has read and write permissions and the members of the owner's primary group have read permissions. valid users = %S prevents read access even if the group has read permissions. For the group to have read or write access, deactivate the line valid users = %S.

Warning
Warning: Do not share NFS mounts with Samba

Sharing NFS mounts with samba may result in data loss and is not supported. Install Samba directly on the file server or consider using alternatives such as iSCSI.

28.4.2.3 Security Levels

To improve security, each share access can be protected with a password. SMB offers the following ways of checking permissions:

User Level Security (security = user)

This variant introduces the concept of the user to SMB. Each user must register with the server with his or her own password. After registration, the server can grant access to individual exported shares dependent on user names.

ADS Level Security (security = ADS)

In this mode, Samba will act as a domain member in an Active Directory environment. To operate in this mode, the machine running Samba needs Kerberos installed and configured. You must join the machine using Samba to the ADS realm. This can be done using the YaST Windows Domain Membership module.

Domain Level Security (security = domain)

This mode will only work correctly if the machine has been joined into a Windows NT Domain. Samba will try to validate user name and password by passing it to a Windows NT Primary or Backup Domain Controller. The same way as a Windows NT Server would do. It expects the encrypted passwords parameter to be set to yes.

The selection of share, user, server, or domain level security applies to the entire server. It is not possible to offer individual shares of a server configuration with share level security and others with user level security. However, you can run a separate Samba server for each configured IP address on a system.

More information about this subject can be found in the Samba 3 HOWTO. For multiple servers on one system, pay attention to the options interfaces and bind interfaces only.

28.5 Configuring Clients

Clients can only access the Samba server via TCP/IP. NetBEUI and NetBIOS via IPX cannot be used with Samba.

28.5.1 Configuring a Samba Client with YaST

Configure a Samba client to access resources (files or printers) on the Samba or Windows server. Enter the NT or Active Directory domain or workgroup in the dialog Network Services › Windows Domain Membership. If you activate Also Use SMB Information for Linux Authentication, the user authentication runs over the Samba, NT or Kerberos server.

Click Expert Settings for advanced configuration options. For example, use the Mount Server Directories table to enable mounting server home directory automatically with authentication. This way users can access their home directories when hosted on CIFS. For details, see the pam_mount man page.

After completing all settings, confirm the dialog to finish the configuration.

28.6 Samba as Login Server

In networks where predominantly Windows clients are found, it is often preferable that users may only register with a valid account and password. In a Windows-based network, this task is handled by a primary domain controller (PDC). You can use a Windows NT server configured as PDC, but this task can also be done with a Samba server. The entries that must be made in the [global] section of smb.conf are shown in Example 28.3, “Global Section in smb.conf”.

Example 28.3: Global Section in smb.conf
[global]
    workgroup = WORKGROUP
    domain logons = Yes
    domain master = Yes

It is necessary to prepare user accounts and passwords in an encryption format that conforms with Windows. Do this with the command smbpasswd -a name. Create the domain account for the computers, required by the Windows domain concept, with the following commands:

useradd hostname\$
smbpasswd -a -m hostname

With the useradd command, a dollar sign is added. The command smbpasswd inserts this automatically when the parameter -m is used. The commented configuration example (/usr/share/doc/packages/samba/examples/smb.conf.SUSE) contains settings that automate this task.

add machine script = /usr/sbin/useradd -g nogroup -c "NT Machine Account" \
-s /bin/false %m\$

To make sure that Samba can execute this script correctly, choose a Samba user with the required administrator permissions and add it to the ntadmin group. Then all users belonging to this Linux group can be assigned Domain Admin status with the command:

net groupmap add ntgroup="Domain Admins" unixgroup=ntadmin

28.7 Samba Server in the Network with Active Directory

If you run Linux servers and Windows servers together, you can build two independent authentication systems and networks or connect servers to one network with one central authentication system. Because Samba can cooperate with an active directory domain, you can join your SUSE Linux Enterprise Server to Active Directory (AD).

To join an AD domain proceed as follows:

  1. Log in as root and start YaST.

  2. Start Network Services › Windows Domain Membership.

  3. Enter the domain to join at Domain or Workgroup in the Windows Domain Membership screen.

    Determining Windows Domain Membership
    Figure 28.1: Determining Windows Domain Membership
  4. Check Also Use SMB Information for Linux Authentication to use the SMB source for Linux authentication on your server.

  5. Click OK and confirm the domain join when prompted for it.

  6. Provide the password for the Windows Administrator on the AD server and click OK.

    Your server is now set up to pull in all authentication data from the Active Directory domain controller.

Tip
Tip: Identity Mapping

In an environment with more than one Samba server, UIDs and GIDs will not be created consistently. The UIDs that get assigned to users will be dependent on the order in which they first log in, which results in UID conflicts across servers. To fix this, you need to use identity mapping. See https://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/idmapper.html for more details.

28.8 Advanced Topics

This section introduces more advanced techniques to manage both the client and server part of the Samba suite.

28.8.1 Transparent File Compression on Btrfs

Samba allows clients to remotely manipulate file and directory compression flags for shares placed on the Btrfs file system. Windows Explorer provides the ability to flag files/directories for transparent compression via the File › Properties › Advanced dialog:

Windows Explorer Advanced Attributes Dialog
Figure 28.2: Windows Explorer Advanced Attributes Dialog

Files flagged for compression are transparently compressed and decompressed by the underlying file system when accessed or modified. This normally results in storage capacity savings at the expense of extra CPU overhead when accessing the file. New files and directories inherit the compression flag from the parent directory, unless created with the FILE_NO_COMPRESSION option.

Windows Explorer presents compressed files and directories visually differently to those that are not compressed:

Windows Explorer Directory Listing with Compressed Files
Figure 28.3: Windows Explorer Directory Listing with Compressed Files

You can enable Samba share compression either manually by adding

vfs objects = btrfs

to the share configuration in /etc/samba/smb.conf, or using YaST: Network Services › Samba Server › Add, and checking Utilize Btrfs Features.

A general overview of compression on Btrfs can be found in Section 1.2.2.1, “Mounting Compressed Btrfs File Systems”.

28.8.2 Snapshots

Snapshots, also called Shadow Copies, are copies of the state of a file system subvolume at a certain point of time. Snapper is the tool to manage these snapshots in Linux. Snapshots are supported on the Btrfs file system or thin-provisioned LVM volumes. The Samba suite supports managing of remote snapshots through the FSRVP protocol on both the server and client side.

28.8.2.1 Previous Versions

Snapshots on a Samba server can be exposed to remote Windows clients as file or directory previous versions.

To enable snapshots on a Samba server, the following conditions must be fulfilled:

  • The SMB network share resides on a Btrfs subvolume.

  • The SMB network share path has a related snapper configuration file. You can create the snapper file with

    snapper -c <cfg_name> create-config /path/to/share

    For more information on snapper, see Chapter 7, System Recovery and Snapshot Management with Snapper.

  • The snapshot directory tree must allow access for relevant users. For more information, see the PERMISSIONS section of the vfs_snapper manual page (man 8 vfs_snapper).

To support remote snapshots, you need to modify the /etc/samba/smb.conf file. You can do it either with YaST › Network Services › Samba Server, or manually by enhancing the relevant share section with

vfs objects = snapper

Note that you need to restart the Samba service for manual smb.conf changes to take effect:

systemctl restart nmb smb
Adding a New Samba Share with Snapshotting Enabled
Figure 28.4: Adding a New Samba Share with Snapshotting Enabled

After being configured, snapshots created by snapper for the Samba share path can be accessed from Windows Explorer from a file or directory's Previous Versions tab.

The Previous Versions tab in Windows Explorer
Figure 28.5: The Previous Versions tab in Windows Explorer

28.8.2.2 Remote Share Snapshots

By default, snapshots can only be created and deleted on the Samba server locally, via the snapper command line utility, or using snapper's time line feature.

Samba can be configured to process share snapshot creation and deletion requests from remote hosts using the File Server Remote VSS Protocol (FSRVP).

In addition to the configuration and prerequisites documented in Section 28.8.2.1, “Previous Versions”, the following global configuration is required in /etc/samba/smb.conf:

[global]
rpc_daemon:fssd = fork
registry shares = yes
include = registry

FSRVP clients, including Samba's rpcclient and Windows Server 2012 DiskShadow.exe, can then instruct Samba to create or delete a snapshot for a given share, and expose the snapshot as a new share.

28.8.2.3 Managing Snapshots Remotely from Linux with rpcclient

The samba-client package contains an FSRVP client that can remotely request a Windows/Samba server to create and expose a snapshot of a given share. You can then use existing tools in SUSE Linux Enterprise Server to mount the exposed share and back up its files. Requests to the server are sent using the rpcclient binary.

Example 28.4: Using rpcclient to Request a Windows Server 2012 Share Snapshot

Connect to win-server.example.com server as an administrator in an EXAMPLE domain:

# rpcclient -U 'EXAMPLE\Administrator' ncacn_np:win-server.example.com[ndr64,sign]
Enter EXAMPLE/Administrator's password:

Check that the SMB share is visible for rpcclient:

rpcclient $> netshareenum
netname: windows_server_2012_share
remark:
path:   C:\Shares\windows_server_2012_share
password:       (null)

Check that the SMB share supports snapshot creation:

rpcclient $> fss_is_path_sup windows_server_2012_share \
UNC \\WIN-SERVER\windows_server_2012_share\ supports shadow copy requests

Request the creation of a share snapshot:

rpcclient $> fss_create_expose backup ro windows_server_2012_share
13fe880e-e232-493d-87e9-402f21019fb6: shadow-copy set created
13fe880e-e232-493d-87e9-402f21019fb6(1c26544e-8251-445f-be89-d1e0a3938777): \
\\WIN-SERVER\windows_server_2012_share\ shadow-copy added to set
13fe880e-e232-493d-87e9-402f21019fb6: prepare completed in 0 secs
13fe880e-e232-493d-87e9-402f21019fb6: commit completed in 1 secs
13fe880e-e232-493d-87e9-402f21019fb6(1c26544e-8251-445f-be89-d1e0a3938777): \
share windows_server_2012_share@{1C26544E-8251-445F-BE89-D1E0A3938777} \
exposed as a snapshot of \\WIN-SERVER\windows_server_2012_share\

Confirm that the snapshot share is exposed by the server:

rpcclient $> netshareenum
netname: windows_server_2012_share
remark:
path:   C:\Shares\windows_server_2012_share
password:       (null)

netname: windows_server_2012_share@{1C26544E-8251-445F-BE89-D1E0A3938777}
remark: (null)
path:   \\?\GLOBALROOT\Device\HarddiskVolumeShadowCopy{F6E6507E-F537-11E3-9404-B8AC6F927453}\Shares\windows_server_2012_share\
password:       (null)

Attempt to delete the snapshot share:

rpcclient $> fss_delete windows_server_2012_share \
13fe880e-e232-493d-87e9-402f21019fb6 1c26544e-8251-445f-be89-d1e0a3938777
13fe880e-e232-493d-87e9-402f21019fb6(1c26544e-8251-445f-be89-d1e0a3938777): \
\\WIN-SERVER\windows_server_2012_share\ shadow-copy deleted

Confirm that the snapshot share has been removed by the server:

rpcclient $> netshareenum
netname: windows_server_2012_share
remark:
path:   C:\Shares\windows_server_2012_share
password:       (null)

28.8.2.4 Managing Snapshots Remotely from Windows with DiskShadow.exe

You can manage snapshots of SMB shares on the Linux Samba server from the Windows environment acting as a client as well. Windows Server 2012 includes the DiskShadow.exe utility that can manage remote shares similar to the rpcclient described in Section 28.8.2.3, “Managing Snapshots Remotely from Linux with rpcclient. Note that you need to carefully set up the Samba server first.

Following is an example procedure to set up the Samba server so that the Windows Server client can manage its share's snapshots. Note that EXAMPLE is the Active Directory domain used in the testing environment, fsrvp-server.example.com is the host name of the Samba server, and /srv/smb is the path to the SMB share.

Procedure 28.1: Detailed Samba Server Configuration
  1. Join Active Directory domain via YaST. For more information, Section 28.7, “Samba Server in the Network with Active Directory”.

  2. Ensure that the Active Domain DNS entry was correct:

    fsrvp-server:~ # net -U 'Administrator' ads dns register \
    fsrvp-server.example.com <IP address>
    Successfully registered hostname with DNS
  3. Create Btrfs subvolume at /srv/smb

    fsrvp-server:~ # btrfs subvolume create /srv/smb
  4. Create snapper configuration file for path /srv/smb

    fsrvp-server:~ # snapper -c <snapper_config> create-config /srv/smb
  5. Create new share with path /srv/smb, and YaST Expose Snapshots check box enabled. Make sure to add the following snippets to the global section of /etc/samba/smb.conf as mentioned in Section 28.8.2.2, “Remote Share Snapshots”:

    [global]
     rpc_daemon:fssd = fork
     registry shares = yes
     include = registry
  6. Restart Samba with systemctl restart nmb smb

  7. Configure snapper permissions:

    fsrvp-server:~ # snapper -c <snapper_config> set-config \
    ALLOW_USERS="EXAMPLE\\\\Administrator EXAMPLE\\\\win-client$"

    Ensure that any ALLOW_USERS are also permitted traversal of the .snapshots subdirectory.

    fsrvp-server:~ # snapper -c <snapper_config> set-config SYNC_ACL=yes
    Important
    Important: Path Escaping

    Be careful about the '\' escapes! Escape twice to ensure that the value stored in /etc/snapper/configs/<snapper_config> is escaped once.

    "EXAMPLE\win-client$" corresponds to the Windows client computer account. Windows issues initial FSRVP requests while authenticated with this account.

  8. Grant Windows client account necessary privileges:

    fsrvp-server:~ # net -U 'Administrator' rpc rights grant \
    "EXAMPLE\\win-client$" SeBackupPrivilege
    Successfully granted rights.

    The previous command is not needed for the "EXAMPLE\Administrator" user, which has privileges already granted.

Procedure 28.2: Windows Client Setup and DiskShadow.exe in Action
  1. Boot Windows Server 2012 (example host name WIN-CLIENT).

  2. Join the same Active Directory domain EXAMPLE as with the SUSE Linux Enterprise Server.

  3. Reboot.

  4. Open Powershell.

  5. Start DiskShadow.exe and begin the backup procedure:

    PS C:\Users\Administrator.EXAMPLE> diskshadow.exe
    Microsoft DiskShadow version 1.0
    Copyright (C) 2012 Microsoft Corporation
    On computer:  WIN-CLIENT,  6/17/2014 3:53:54 PM
    
    DISKSHADOW> begin backup
  6. Specify that shadow copy persists across program exit, reset or reboot:

    DISKSHADOW> set context PERSISTENT
  7. Check whether the specified share supports snapshots, and create one:

    DISKSHADOW> add volume \\fsrvp-server\sles_snapper
    
    DISKSHADOW> create
    Alias VSS_SHADOW_1 for shadow ID {de4ddca4-4978-4805-8776-cdf82d190a4a} set as \
     environment variable.
    Alias VSS_SHADOW_SET for shadow set ID {c58e1452-c554-400e-a266-d11d5c837cb1} \
     set as environment variable.
    
    Querying all shadow copies with the shadow copy set ID \
     {c58e1452-c554-400e-a266-d11d5c837cb1}
    
     * Shadow copy ID = {de4ddca4-4978-4805-8776-cdf82d190a4a}     %VSS_SHADOW_1%
        - Shadow copy set: {c58e1452-c554-400e-a266-d11d5c837cb1}  %VSS_SHADOW_SET%
        - Original count of shadow copies = 1
        - Original volume name: \\FSRVP-SERVER\SLES_SNAPPER\ \
          [volume not on this machine]
        - Creation time: 6/17/2014 3:54:43 PM
        - Shadow copy device name:
          \\FSRVP-SERVER\SLES_SNAPPER@{31afd84a-44a7-41be-b9b0-751898756faa}
        - Originating machine: FSRVP-SERVER
        - Service machine: win-client.example.com
        - Not exposed
        - Provider ID: {89300202-3cec-4981-9171-19f59559e0f2}
        - Attributes:  No_Auto_Release Persistent FileShare
    
    Number of shadow copies listed: 1
  8. Finish the backup procedure:

    DISKSHADOW> end backup
  9. After the snapshot was created, try to delete it and verify the deletion:

    DISKSHADOW> delete shadows volume \\FSRVP-SERVER\SLES_SNAPPER\
    Deleting shadow copy {de4ddca4-4978-4805-8776-cdf82d190a4a} on volume \
     \\FSRVP-SERVER\SLES_SNAPPER\ from provider \
    {89300202-3cec-4981-9171-19f59559e0f2} [Attributes: 0x04000009]...
    
    Number of shadow copies deleted: 1
    
    DISKSHADOW> list shadows all
    
    Querying all shadow copies on the computer ...
    No shadow copies found in system.

28.9 For More Information

Documentation for Samba ships with the samba-doc package which is not installed by default. Install it with zypper install samba-doc. Enter apropos samba at the command line to display some manual pages or browse the /usr/share/doc/packages/samba directory for more online documentation and examples. Find a commented example configuration (smb.conf.SUSE) in the examples subdirectory. Another file to look for Samba related information is /usr/share/doc/packages/samba/README.SUSE.

The Samba HOWTO (see https://wiki.samba.org) provided by the Samba team includes a section about troubleshooting. In addition to that, Part V of the document provides a step-by-step guide to checking your configuration.

29 On-Demand Mounting with Autofs

  • Filename: autofs.xml
  • ID: cha.autofs
Abstract

autofs is a program that automatically mounts specified directories on an on-demand basis. It is based on a kernel module for high efficiency, and can manage both local directories and network shares. These automatic mount points are mounted only when they are accessed, and unmounted after a certain period of inactivity. This on-demand behavior saves bandwidth and results in better performance than static mounts managed by /etc/fstab. While autofs is a control script, automount is the command (daemon) that does the actual auto-mounting.

29.1 Installation

autofs is not installed on SUSE Linux Enterprise Server by default. To use its auto-mounting capabilities, first install it with

sudo zypper install autofs

29.2 Configuration

You need to configure autofs manually by editing its configuration files with a text editor, such as vim. There are two basic steps to configure autofs—the master map file, and specific map files.

29.2.1 The Master Map File

The default master configuration file for autofs is /etc/auto.master. You can change its location by changing the value of the DEFAULT_MASTER_MAP_NAME option in /etc/sysconfig/autofs. Here is the content of the default one for SUSE Linux Enterprise Server:

#
# Sample auto.master file
# This is an automounter map and it has the following format
# key [ -mount-options-separated-by-comma ] location
# For details of the format look at autofs(5).1
#
#/misc  /etc/auto.misc2
#/net -hosts
#
# Include /etc/auto.master.d/*.autofs3
#
#+dir:/etc/auto.master.d
#
# Include central master map if it can be found using
# nsswitch sources.
#
# Note that if there are entries for /net or /misc (as
# above) in the included master map any keys that are the
# same will not be seen as the first read key seen takes
# precedence.
#
+auto.master4

1

The autofs manual page (man 5 autofs) offers a lot of valuable information on the format of the automounter maps.

2

Although commented out (#) by default, this is an example of a simple automounter mapping syntax.

3

In case you need to split the master map into several files, uncomment the line, and put the mappings (suffixed with .autofs) in the /etc/auto.master.d/ directory.

4

+auto.master ensures that those using NIS (see Section 3.1, “Configuring NIS Servers” for more information on NIS) will still find their master map.

Entries in auto.master have three fields with the following syntax:

mount point      map name      options
mount point

The base location where to mount the autofs file system, such as /home.

map name

The name of a map source to use for mounting. For the syntax of the maps files, see Section 29.2.2, “Map Files”.

options

These options (if specified) will apply as defaults to all entries in the given map.

Tip
Tip: For More Information

For more detailed information on the specific values of the optional map-type, format, and options, see the auto.master manual page (man 5 auto.master).

The following entry in auto.master tells autofs to look in /etc/auto.smb, and create mount points in the /smb directory.

/smb   /etc/auto.smb

29.2.1.1 Direct Mounts

Direct mounts create a mount point at the path specified inside the relevant map file. Instead of specifying the mount point in auto.master, replace the mount point field with /-. For example, the following line tells autofs to create a mount point at the place specified in auto.smb:

/-        /etc/auto.smb
Tip
Tip: Maps without Full Path

If the map file is not specified with its full local or network path, it is located using the Name Service Switch (NSS) configuration:

/-        auto.smb

29.2.2 Map Files

Important
Important: Other Types of Maps

Although files are the most common types of maps for auto-mounting with autofs, there are other types as well. A map specification can be the output of a command, or a result of a query in LDAP or database. For more detailed information on map types, see the manual page man 5 auto.master.

Map files specify the (local or network) source location, and the mount point where to mount the source locally. The general format of maps is similar to the master map. The difference is that the options appear between the mount point and the location instead of at the end of the entry:

mount point      options      location

Make sure that map files are not marked as executable. You can remove the executable bits by executing chmod -x MAP_FILE.

mount point

Specifies where to mount the source location. This can be either a single directory name (so-called indirect mount) to be added to the base mount point specified in auto.master, or the full path of the mount point (direct mount, see Section 29.2.1.1, “Direct Mounts”).

options

Specifies optional comma-separated list of mount options for the relevant entries. If auto.master contains options for this map file as well, theses are appended.

location

Specifies from where the file system is to be mounted. It is usually an NFS or SMB volume in the usual notation host_name:path_name. If the file system to be mounted begins with a '/' (such as local /dev entries or smbfs shares), a colon symbol ':' needs to be prefixed, such as :/dev/sda1.

29.3 Operation and Debugging

This section introduces information on how to control the autofs service operation, and how to view more debugging information when tuning the automounter operation.

29.3.1 Controlling the autofs Service

The operation of the autofs service is controlled by systemd. The general syntax of the systemctl command for autofs is

sudo systemctl SUB_COMMAND autofs

where SUB_COMMAND is one of:

enable

Starts the automounter daemon at boot.

start

Starts the automounter daemon.

stop

Stops the automounter daemon. Automatic mount points are not accessible.

status

Prints the current status of the autofs service together with a part of a relevant log file.

restart

Stops and starts the automounter, terminating all running daemons and starting new ones.

reload

Checks the current auto.master map, restarts those daemons whose entries have changed, and starts new ones for new entries.

29.3.2 Debugging the Automounter Problems

If you experience problems when mounting directories with autofs, it is useful to run the automount daemon manually and watch its output messages:

  1. Stop autofs.

    sudo systemctl stop autofs
  2. From one terminal, run automount manually in the foreground, producing verbose output.

    sudo automount -f -v
  3. From another terminal, try to mount the auto-mounting file systems by accessing the mount points (for example by cd or ls).

  4. Check the output of automount from the first terminal for more information why the mount failed, or why it was not even attempted.

29.4 Auto-Mounting an NFS Share

The following procedure illustrates how to configure autofs to auto-mount an NFS share available on your network. It makes use of the information mentioned above, and assumes you are familiar with NFS exports. For more information on NFS, see Chapter 27, Sharing File Systems with NFS.

  1. Edit the master map file /etc/auto.master:

    sudo vim /etc/auto.master

    Add a new entry for the new NFS mount at the end of /etc/auto.master:

    /nfs      /etc/auto.nfs      --timeout=10

    It tells autofs that the base mount point is /nfs, the NFS shares are specified in the /etc/auto.nfs map, and that all shares in this map will be automatically unmounted after 10 seconds of inactivity.

  2. Create a new map file for NFS shares:

    sudo vim /etc/auto.nfs

    /etc/auto.nfs normally contains a separate line for each NFS share. Its format is described in Section 29.2.2, “Map Files”. Add the line describing the mount point and the NFS share network address:

    export      jupiter.com:/home/geeko/doc/export

    The above line means that the /home/geeko/doc/export directory on the jupiter.com host will be auto-mounted to the /nfs/export directory on the local host (/nfs is taken from the auto.master map) when requested. The /nfs/export directory will be created automatically by autofs.

  3. Optionally comment out the related line in /etc/fstab if you previously mounted the same NFS share statically. The line should look similar to this:

    #jupiter.com:/home/geeko/doc/export /nfs/export nfs defaults 0 0
  4. Reload autofs and check if it works:

    sudo systemctl restart autofs
    # ls -l /nfs/export
    total 20
    drwxr-xr-x  6 1001 users 4096 Oct 25 08:56 ./
    drwxr-xr-x  3 root root     0 Apr  1 09:47 ../
    drwxr-xr-x  5 1001 users 4096 Jan 14  2013 .images/
    drwxr-xr-x 10 1001 users 4096 Aug 16  2013 .profiled/
    drwxr-xr-x  3 1001 users 4096 Aug 30  2013 .tmp/
    drwxr-xr-x  4 1001 users 4096 Oct 25 08:56 SLE-12-manual/

    If you can see the list of files on the remote share, then autofs is functioning.

29.5 Advanced Topics

This section describes topics that are beyond the basic introduction to autofs—auto-mounting of NFS shares that are available on your network, using wild cards in map files, and information specific to the CIFS file system.

29.5.1 /net Mount Point

This helper mount point is useful if you use a lot of NFS shares. /net auto-mounts all NFS shares on your local network on demand. The entry is already present in the auto.master file, so all you need to do is uncomment it and restart autofs:

/net      -hosts
systemctl restart autofs

For example, if you have a server named jupiter with an NFS share called /export, you can mount it by typing

# cd /net/jupiter/export

on the command line.

29.5.2 Using Wild Cards to Auto-Mount Subdirectories

If you have a directory with subdirectories that you need to auto-mount individually—the typical case is the /home directory with individual users' home directories inside— autofs offers a clever solution for that.

In case of home directories, add the following line in auto.master:

/home      /etc/auto.home

Now you need to add the correct mapping to the /etc/auto.home file, so that the users' home directories are mounted automatically. One solution is to create separate entries for each directory:

wilber      jupiter.com:/home/wilber
penguin      jupiter.com:/home/penguin
tux      jupiter.com:/home/tux
[...]

This is very awkward as you need to manage the list of users inside auto.home. You can use the asterisk '*' instead of the mount point, and the ampersand '&' instead of the directory to be mounted:

*      jupiter:/home/&

29.5.3 Auto-Mounting CIFS File System

If you want to auto-mount an SMB/CIFS share (see Chapter 28, Samba for more information on the SMB/CIFS protocol), you need to modify the syntax of the map file. Add -fstype=cifs in the option field, and prefix the share location with a colon ':'.

mount point      -fstype=cifs      ://jupiter.com/export

30 SLP

  • Filename: net_slp.xml
  • ID: cha.slp
Abstract

Configuring a network client requires detailed knowledge about services provided over the network (such as printing or LDAP, for example). To make it easier to configure such services on a network client, the service location protocol (SLP) was developed. SLP makes the availability and configuration data of selected services known to all clients in the local network. Applications that support SLP can use this information to be configured automatically.

SUSE® Linux Enterprise Server supports installation using installation sources provided with SLP and contains many system services with integrated support for SLP. You can use SLP to provide networked clients with central functions, such as an installation server, file server, or print server on your system. Services that offer SLP support include cupsd, login, ntp, openldap2, postfix, rpasswd, rsyncd, saned, sshd (via fish), vnc, and ypserv.

All packages necessary to use SLP services on a network client are installed by default. However, if you want to provide services via SLP, check that the openslp-server package is installed.

30.1 The SLP Front-End slptool

slptool is a command line tool to query and register SLP services. The query functions are useful for diagnostic purposes. The most important slptool subcommands are listed below. slptool --help lists all available options and functions.

findsrvtypes

List all service types available on the network.

tux >  slptool findsrvtypes
service:install.suse:nfs
service:install.suse:ftp
service:install.suse:http
service:install.suse:smb
service:ssh
service:fish
service:YaST.installation.suse:vnc
service:smtp
service:domain
service:management-software.IBM:hardware-management-console
service:rsync
service:ntp
service:ypserv
findsrvs SERVICE_TYPE

List all servers providing SERVICE_TYPE

tux >  slptool findsrvs service:ntp
service:ntp://ntp.example.com:123,57810
service:ntp://ntp2.example.com:123,57810
findattrs SERVICE_TYPE//HOST

List attributes for SERVICE_TYPE on HOST

tux >  slptool findattrs service:ntp://ntp.example.com
(owner=tux),(email=tux@example.com)
register SERVICE type//HOST:PORT "(ATTRIBUTE=VALUE),(ATTRIBUTE=VALUE)"

Registers SERVICE_TYPE on HOST with an optional list of attributes

slptool register service:ntp://ntp.example.com:57810 \
"(owner=tux),(email=tux@example.com)"
deregister SERVICE_TYPE//host

De-registers SERVICE_TYPE on HOST

slptool deregister service:ntp://ntp.example.com

For more information run slptool --help.

30.2 Providing Services via SLP

To provide SLP services, the SLP daemon (slpd) must be running. Like most system services in SUSE Linux Enterprise Server, slpd is controlled by means of a separate start script. After the installation, the daemon is inactive by default. To activate it for the current session, run sudo systemctl start slpd. If slpd should be activated on system start-up, run sudo systemctl enable slpd.

Many applications in SUSE Linux Enterprise Server have integrated SLP support via the libslp library. If a service has not been compiled with SLP support, use one of the following methods to make it available via SLP:

Static Registration with /etc/slp.reg.d

Create a separate registration file for each new service. The following example registers a scanner service:

## Register a saned service on this system
## en means english language
## 65535 disables the timeout, so the service registration does
## not need refreshes
service:scanner.sane://$HOSTNAME:6566,en,65535
watch-port-tcp=6566
description=SANE scanner daemon

The most important line in this file is the service URL, which begins with service:. This contains the service type (scanner.sane) and the address under which the service is available on the server. $HOSTNAME is automatically replaced with the full host name. The name of the TCP port on which the relevant service can be found follows, separated by a colon. Then enter the language in which the service should appear and the duration of registration in seconds. These should be separated from the service URL by commas. Set the value for the duration of registration between 0 and 65535. 0 prevents registration. 65535 removes all restrictions.

The registration file also contains the two variables watch-port-tcp and description. watch-port-tcp links the SLP service announcement to whether the relevant service is active by having slpd check the status of the service. The second variable contains a more precise description of the service that is displayed in suitable browsers.

Tip
Tip: YaST and SLP

Some services brokered by YaST, such as an installation server or YOU server, perform this registration automatically when you activate SLP in the module dialogs. YaST then creates registration files for these services.

Static Registration with /etc/slp.reg

The only difference between this method and the procedure with /etc/slp.reg.d is that all services are grouped within a central file.

Dynamic Registration with slptool

If a service needs to be registered dynamically without the need of configuration files, use the slptool command line utility. The same utility can also be used to de-register an existing service offering without restarting slpd. See Section 30.1, “The SLP Front-End slptool for details.

30.2.1 Setting up an SLP Installation Server

Announcing the installation data via SLP within your network makes the network installation much easier, since the installation data such as IP address of the server or the path to the installation media are automatically required via SLP query. Refer to Chapter 8, Setting Up the Server Holding the Installation Sources for instructions.

30.3 For More Information

RFC 2608, 2609, 2610

RFC 2608 generally deals with the definition of SLP. RFC 2609 deals with the syntax of the service URLs used in greater detail and RFC 2610 deals with DHCP via SLP.

http://www.openslp.org

The home page of the OpenSLP project.

/usr/share/doc/packages/openslp

This directory contains the documentation for SLP coming with the openslp-server package, including a README.SUSE containing the SUSE Linux Enterprise Server details, the RFCs, and two introductory HTML documents. Programmers who want to use the SLP functions will find more information in the Programmers Guide that is included in the openslp-devel package that is provided with the SUSE Software Development Kit.

31 The Apache HTTP Server

  • Filename: apache2.xml
  • ID: cha.apache2
Abstract

According to the survey from http://www.netcraft.com/, the Apache HTTP Server (Apache) is the world's most widely-used Web server. Developed by the Apache Software Foundation (http://www.apache.org/), it is available for most operating systems. SUSE® Linux Enterprise Server includes Apache version 2.4. In this chapter, learn how to install, configure and set up a Web server; how to use SSL, CGI, and additional modules; and how to troubleshoot Apache.

31.1 Quick Start

With this section, quickly set up and start Apache. You must be root to install and configure Apache.

31.1.1 Requirements

Make sure the following requirements are met before trying to set up the Apache Web server:

  1. The machine's network is configured properly. For more information about this topic, refer to Chapter 16, Basic Networking.

  2. The machine's exact system time is maintained by synchronizing with a time server. This is necessary because parts of the HTTP protocol depend on the correct time. See Chapter 24, Time Synchronization with NTP to learn more about this topic.

  3. The latest security updates are installed. If in doubt, run a YaST Online Update.

  4. The default Web server port (80) is opened in the firewall. For this, configure the SuSEFirewall2 to allow the service HTTP Server in the external zone. This can be done using YaST. See Section 15.4.1, “Configuring the Firewall with YaST” for details.

31.1.2 Installation

Apache on SUSE Linux Enterprise Server is not installed by default. To install it with a standard, predefined configuration that runs out of the box, proceed as follows:

Procedure 31.1: Installing Apache with the Default Configuration
  1. Start YaST and select Software › Software Management.

  2. Choose View › Patterns and select Web and LAMP Server.

  3. Confirm the installation of the dependent packages to finish the installation process.

31.1.3 Start

You can start Apache automatically at boot time or start it manually.

To make sure that Apache is automatically started during boot in the targets multi-user.target and graphical.target, execute the following command:

root # systemctl enable apache2

For more information about the systemd targets in SUSE Linux Enterprise Server and a description of the YaST Services Manager, refer to Section 13.4, “Managing Services with YaST”.

To manually start Apache using the shell, run systemctl start apache2.

Procedure 31.2: Checking if Apache is Running

If you do not receive error messages when starting Apache, this usually indicates that the Web server is running. To test this:

  1. Start a browser and open http://localhost/.

    If Apache is up and running, you get a test page stating It works!.

  2. If you do not see this page, refer to Section 31.9, “Troubleshooting”.

Now that the Web server is running, you can add your own documents, adjust the configuration according to your needs, or add functionality by installing modules.

31.2 Configuring Apache

SUSE Linux Enterprise Server offers two configuration options:

Manual configuration offers a higher level of detail, but lacks the convenience of the YaST GUI.

Important
Important: Reload or Restart Apache after Configuration Changes

Most configuration changes require a reload (some also a restart) of Apache to take effect. Manually reload Apache with systemctl reload apache2 or use one of the restart options as described in Section 31.3, “Starting and Stopping Apache”.

If you configure Apache with YaST, this can be taken care of automatically if you set HTTP Service to Enabled as described in Section 31.2.3.2, “HTTP Server Configuration”.

31.2.1 Apache Configuration Files

This section gives an overview of the Apache configuration files. If you use YaST for configuration, you do not need to touch these files—however, the information might be useful for you if you want to switch to manual configuration later on.

Apache configuration files can be found in two different locations:

31.2.1.1 /etc/sysconfig/apache2

/etc/sysconfig/apache2 controls some global settings of Apache, like modules to load, additional configuration files to include, flags with which the server should be started, and flags that should be added to the command line. Every configuration option in this file is extensively documented and therefore not mentioned here. For a general-purpose Web server, the settings in /etc/sysconfig/apache2 should be sufficient for any configuration needs.

31.2.1.2 /etc/apache2/

/etc/apache2/ hosts all configuration files for Apache. In the following, the purpose of each file is explained. Each file includes several configuration options (also called directives). Every configuration option in these files is extensively documented and therefore not mentioned here.

The Apache configuration files are organized as follows:

/etc/apache2/
     |
     |- charset.conv
     |- conf.d/
     |   |
     |   |- *.conf
     |
     |- default-server.conf
     |- errors.conf
     |- httpd.conf
     |- listen.conf
     |- magic
     |- mime.types
     |- mod_*.conf
     |- server-tuning.conf
     |- ssl.*
     |- ssl-global.conf
     |- sysconfig.d
     |   |
     |   |- global.conf
     |   |- include.conf
     |   |- loadmodule.conf . .
     |
     |- uid.conf
     |- vhosts.d
     |   |- *.conf
Apache Configuration Files in /etc/apache2/
charset.conv

Specifies which character sets to use for different languages. Do not edit this file.

conf.d/*.conf

Configuration files added by other modules. These configuration files can be included into your virtual host configuration where needed. See vhosts.d/vhost.template for examples. By doing so, you can provide different module sets for different virtual hosts.

default-server.conf

Global configuration for all virtual hosts with reasonable defaults. Instead of changing the values, overwrite them with a virtual host configuration.

errors.conf

Defines how Apache responds to errors. To customize these messages for all virtual hosts, edit this file. Otherwise overwrite these directives in your virtual host configurations.

httpd.conf

The main Apache server configuration file. Avoid changing this file. It primarily contains include statements and global settings. Overwrite global settings in the pertinent configuration files listed here. Change host-specific settings (such as document root) in your virtual host configuration.

listen.conf

Binds Apache to specific IP addresses and ports. Name-based virtual hosting is also configured here. For details, see Section 31.2.2.1.1, “Name-Based Virtual Hosts”.

magic

Data for the mime_magic module that helps Apache automatically determine the MIME type of an unknown file. Do not change this file.

mime.types

MIME types known by the system (this actually is a link to /etc/mime.types). Do not edit this file. If you need to add MIME types not listed here, add them to mod_mime-defaults.conf.

mod_*.conf

Configuration files for the modules that are installed by default. Refer to Section 31.4, “Installing, Activating, and Configuring Modules” for details. Note that configuration files for optional modules reside in the directory conf.d.

server-tuning.conf

Contains configuration directives for the different MPMs (see Section 31.4.4, “Multiprocessing Modules”) and general configuration options that control Apache's performance. Properly test your Web server when making changes here.

ssl-global.conf and ssl.*

Global SSL configuration and SSL certificate data. Refer to Section 31.6, “Setting Up a Secure Web Server with SSL” for details.

sysconfig.d/*.conf

Configuration files automatically generated from /etc/sysconfig/apache2. Do not change any of these files—edit /etc/sysconfig/apache2 instead. Do not put other configuration files in this directory.

uid.conf

Specifies under which user and group ID Apache runs. Do not change this file.

vhosts.d/*.conf

Your virtual host configuration should be located here. The directory contains template files for virtual hosts with and without SSL. Every file in this directory ending with .conf is automatically included in the Apache configuration. Refer to Section 31.2.2.1, “Virtual Host Configuration” for details.

31.2.2 Configuring Apache Manually

Configuring Apache manually involves editing plain text configuration files as user root.

31.2.2.1 Virtual Host Configuration

The term virtual host refers to Apache's ability to serve multiple universal resource identifiers (URIs) from the same physical machine. This means that several domains, such as www.example.com and www.example.net, are run by a single Web server on one physical machine.

It is common practice to use virtual hosts to save administrative effort (only a single Web server needs to be maintained) and hardware expenses (each domain does not require a dedicated server). Virtual hosts can be name based, IP based, or port based.

To list all existing virtual hosts, use the command apache2ctl -S. This outputs a list showing the default server and all virtual hosts together with their IP addresses and listening ports. Furthermore, the list also contains an entry for each virtual host showing its location in the configuration files.

Virtual hosts can be configured via YaST as described in Section 31.2.3.1.4, “Virtual Hosts” or by manually editing a configuration file. By default, Apache in SUSE Linux Enterprise Server is prepared for one configuration file per virtual host in /etc/apache2/vhosts.d/. All files in this directory with the extension .conf are automatically included to the configuration. A basic template for a virtual host is provided in this directory (vhost.template or vhost-ssl.template for a virtual host with SSL support).

Tip
Tip: Always Create a Virtual Host Configuration

It is recommended to always create a virtual host configuration file, even if your Web server only hosts one domain. By doing so, you not only have the domain-specific configuration in one file, but you can always fall back to a working basic configuration by simply moving, deleting, or renaming the configuration file for the virtual host. For the same reason, you should also create separate configuration files for each virtual host.

When using name-based virtual hosts it is recommended to set up a default configuration that will be used when a domain name does not match a virtual host configuration. The default virtual host is the one whose configuration is loaded first. Since the order of the configuration files is determined by file name, start the file name of the default virtual host configuration with an underscore character (_) to make sure it is loaded first (for example: _default_vhost.conf).

The <VirtualHost></VirtualHost> block holds the information that applies to a particular domain. When Apache receives a client request for a defined virtual host, it uses the directives enclosed in this section. Almost all directives can be used in a virtual host context. See http://httpd.apache.org/docs/2.4/mod/quickreference.html for further information about Apache's configuration directives.

31.2.2.1.1 Name-Based Virtual Hosts

With name-based virtual hosts, more than one Web site is served per IP address. Apache uses the host field in the HTTP header that is sent by the client to connect the request to a matching ServerName entry of one of the virtual host declarations. If no matching ServerName is found, the first specified virtual host is used as a default.

The first step is to create a <VirtualHost> block for each different name-based host that you want to serve. Inside each <VirtualHost> block, you will need at minimum a ServerName directive to designate which host is served and a DocumentRoot directive to show where in the file system the content for that host resides.

Example 31.1: Basic Examples of Name-Based VirtualHost Entries
<VirtualHost *:80>
# This first-listed virtual host is also the default for *:80
ServerName www.example.com
ServerAlias example.com
DocumentRoot /srv/www/htdocs/domain
</VirtualHost>

<VirtualHost *:80>
ServerName other.example.com
DocumentRoot /srv/www/htdocs/otherdomain
</VirtualHost>

The opening VirtualHost tag takes the IP address (or fully qualified domain name) as an argument in a name-based virtual host configuration. A port number directive is optional.

The wild card * is also allowed as a substitute for the IP address. When using IPv6 addresses, the address must be included in square brackets.

Example 31.2: Name-Based VirtualHost Directives
<VirtualHost 192.168.3.100:80>
  ...
</VirtualHost>

<VirtualHost 192.168.3.100>
  ...
</VirtualHost>

<VirtualHost *:80>
  ...
</VirtualHost>

<VirtualHost *>
  ...
</VirtualHost>

<VirtualHost [2002:c0a8:364::]>
  ...
</VirtualHost>
31.2.2.1.2 IP-Based Virtual Hosts

This alternative virtual host configuration requires the setup of multiple IPs for a machine. One instance of Apache hosts several domains, each of which is assigned a different IP.

The physical server must have one IP address for each IP-based virtual host. If the machine does not have multiple network cards, virtual network interfaces (IP aliasing) can also be used.

The following example shows Apache running on a machine with the IP 192.168.3.100, hosting two domains on the additional IPs 192.168.3.101 and 192.168.3.102. A separate VirtualHost block is needed for every virtual server.

Example 31.3: IP-Based VirtualHost Directives
<VirtualHost 192.168.3.101>
  ...
</VirtualHost>

<VirtualHost 192.168.3.102>
  ...
</VirtualHost>

Here, VirtualHost directives are only specified for interfaces other than 192.168.3.100. When a Listen directive is also configured for 192.168.3.100, a separate IP-based virtual host must be created to answer HTTP requests to that interface—otherwise the directives found in the default server configuration (/etc/apache2/default-server.conf) are applied.

31.2.2.1.3 Basic Virtual Host Configuration

At least the following directives should be in each virtual host configuration to set up a virtual host. See /etc/apache2/vhosts.d/vhost.template for more options.

ServerName

The fully qualified domain name under which the host should be addressed.

DocumentRoot

Path to the directory from which Apache should serve files for this host. For security reasons, access to the entire file system is forbidden by default, so you must explicitly unlock this directory within a Directory container.

ServerAdmin

E-mail address of the server administrator. This address is, for example, shown on error pages Apache creates.

ErrorLog

The error log file for this virtual host. Although it is not necessary to create separate error log files for each virtual host, it is common practice to do so, because it makes the debugging of errors much easier. /var/log/apache2/ is the default directory for Apache's log files.

CustomLog

The access log file for this virtual host. Although it is not necessary to create separate access log files for each virtual host, it is common practice to do so, because it allows the separate analysis of access statistics for each host. /var/log/apache2/ is the default directory for Apache's log files.

As mentioned above, access to the whole file system is forbidden by default for security reasons. Therefore, explicitly unlock the directories in which you have placed the files Apache should serve—for example the DocumentRoot:

<Directory "/srv/www/www.example.com/htdocs">
  Require all granted
</Directory>
Note
Note: Require all granted

In previous versions of Apache, the statement Require all granted was expressed as:

Order allow,deny
Allow from all

This old syntax is still supported by the mod_access_compat module.

The complete configuration file looks like this:

Example 31.4: Basic VirtualHost Configuration
<VirtualHost 192.168.3.100>
  ServerName www.example.com
  DocumentRoot /srv/www/www.example.com/htdocs
  ServerAdmin webmaster@example.com
  ErrorLog /var/log/apache2/www.example.com_log
  CustomLog /var/log/apache2/www.example.com-access_log common
  <Directory "/srv/www/www.example.com/htdocs">
  Require all granted
  </Directory>
</VirtualHost>

31.2.3 Configuring Apache with YaST

  • Filename: apache2_yast_i.xml
  • ID: sec.apache2.configuration.yast

To configure your Web server with YaST, start YaST and select Network Services › HTTP Server. When starting the module for the first time, the HTTP Server Wizard starts, prompting you to make a few basic decisions concerning administration of the server. After having finished the wizard, the HTTP Server Configuration dialog starts each time you call the HTTP Server module. For more information, see Section 31.2.3.2, “HTTP Server Configuration”.

31.2.3.1 HTTP Server Wizard

The HTTP Server Wizard consists of five steps. In the last step of the dialog, you may enter the expert configuration mode to make even more specific settings.

31.2.3.1.1 Network Device Selection

Here, specify the network interfaces and ports Apache uses to listen for incoming requests. You can select any combination of existing network interfaces and their respective IP addresses. Ports from all three ranges (well-known ports, registered ports, and dynamic or private ports) that are not reserved by other services can be used. The default setting is to listen on all network interfaces (IP addresses) on port 80.

Check Open Port In Firewall to open the ports in the firewall that the Web server listens on. This is necessary to make the Web server available on the network, which can be a LAN, WAN, or the public Internet. Keeping the port closed is only useful in test situations where no external access to the Web server is necessary. If you have multiple network interfaces, click Firewall Details to specify on which interface(s) the port(s) should be opened.

Click Next to continue with the configuration.

31.2.3.1.2 Modules

The Modules configuration option allows for the activation or deactivation of the script languages that the Web server should support. For the activation or deactivation of other modules, refer to Section 31.2.3.2.2, “Server Modules”. Click Next to advance to the next dialog.

31.2.3.1.3 Default Host

This option pertains to the default Web server. As explained in Section 31.2.2.1, “Virtual Host Configuration”, Apache can serve multiple virtual hosts from a single physical machine. The first declared virtual host in the configuration file is commonly called the default host. Each virtual host inherits the default host's configuration.

To edit the host settings (also called directives), select the appropriate entry in the table then click Edit. To add new directives, click Add. To delete a directive, select it and click Delete.

HTTP Server Wizard: Default Host
Figure 31.1: HTTP Server Wizard: Default Host

Here is list of the default settings of the server:

Document Root

Path to the directory from which Apache serves files for this host. /srv/www/htdocs is the default location.

Alias

Using Alias directives, URLs can be mapped to physical file system locations. This means that a certain path even outside the Document Root in the file system can be accessed via a URL aliasing that path.

The default SUSE Linux Enterprise Server Alias /icons points to /usr/share/apache2/icons for the Apache icons displayed in the directory index view.

ScriptAlias

Similar to the Alias directive, the ScriptAlias directive maps a URL to a file system location. The difference is that ScriptAlias designates the target directory as a CGI location, meaning that CGI scripts should be executed in that location.

Directory

With Directory settings, you can enclose a group of configuration options that will only apply to the specified directory.

Access and display options for the directories /srv/www/htdocs, /usr/share/apache2/icons and /srv/www/cgi-bin are configured here. It should not be necessary to change the defaults.

Include

With include, additional configuration files can be specified. Two Include directives are already preconfigured: /etc/apache2/conf.d/ is the directory containing the configuration files that come with external modules. With this directive, all files in this directory ending in .conf are included. With the second directive, /etc/apache2/conf.d/apache2-manual.conf, the apache2-manual configuration file is included.

Server Name

This specifies the default URL used by clients to contact the Web server. Use a fully qualified domain name (FQDN) to reach the Web server at http://FQDN/ or its IP address. You cannot choose an arbitrary name here—the server must be known under this name.

Server Administrator E-Mail

E-mail address of the server administrator. This address is, for example, shown on error pages Apache creates.

After finishing with the Default Host step, click Next to continue with the configuration.

31.2.3.1.4 Virtual Hosts

In this step, the wizard displays a list of already configured virtual hosts (see Section 31.2.2.1, “Virtual Host Configuration”). If you have not made manual changes prior to starting the YaST HTTP wizard, no virtual host is present.

To add a host, click Add to open a dialog in which to enter basic information about the host, such as Server Name, Server Contents Root (DocumentRoot), and the Administrator E-Mail. Server Resolution is used to determine how a host is identified (name based or IP based). Specify the name or IP address with Change Virtual Host ID

Clicking Next advances to the second part of the virtual host configuration dialog.

In part two of the virtual host configuration you can specify whether to enable CGI scripts and which directory to use for these scripts. It is also possible to enable SSL. If you do so, you must specify the path to the certificate as well. See Section 31.6.2, “Configuring Apache with SSL” for details on SSL and certificates. With the Directory Index option, you can specify which file to display when the client requests a directory (by default, index.html). Add one or more file names (space-separated) to change this. With Enable Public HTML, the content of the users public directories (~USER/public_html/) is made available on the server under http://www.example.com/~USER.

Important
Important: Creating Virtual Hosts

It is not possible to add virtual hosts at will. If using name-based virtual hosts, each host name must be resolved on the network. If using IP-based virtual hosts, you can assign only one host to each IP address available.

31.2.3.1.5 Summary

This is the final step of the wizard. Here, determine how and when the Apache server is started: when booting or manually. Also see a short summary of the configuration made so far. If you are satisfied with your settings, click Finish to complete configuration. To change something, click Back until you have reached the desired dialog. Clicking HTTP Server Expert Configuration opens the dialog described in Section 31.2.3.2, “HTTP Server Configuration”.

HTTP Server Wizard: Summary
Figure 31.2: HTTP Server Wizard: Summary

31.2.3.2 HTTP Server Configuration

The HTTP Server Configuration dialog also lets you make even more adjustments to the configuration than the wizard (which only runs if you configure your Web server for the first time). It consists of four tabs described in the following. No configuration option you change here is effective immediately—you always must confirm your changes with Finish to make them effective. Clicking Abort leaves the configuration module and discards your changes.

31.2.3.2.1 Listen Ports and Addresses

In HTTP Service, select whether Apache should be running (Enabled) or stopped (Disabled). In Listen on Ports, Add, Edit, or Delete addresses and ports on which the server should be available. The default is to listen on all interfaces on port 80. You should always check Open Port In Firewall, because otherwise the Web server is not reachable from outside. Keeping the port closed is only useful in test situations where no external access to the Web server is necessary. If you have multiple network interfaces, click Firewall Details to specify on which interface(s) the port(s) should be opened.

With Log Files, watch either the access log file or the error log file. This is useful if you want to test your configuration. The log file opens in a separate window from which you can also restart or reload the Web server. For details, see Section 31.3, “Starting and Stopping Apache”. These commands are effective immediately and their log messages are also displayed immediately.

HTTP Server Configuration: Listen Ports and Addresses
Figure 31.3: HTTP Server Configuration: Listen Ports and Addresses
31.2.3.2.2 Server Modules

You can change the status (enabled or disabled) of Apache2 modules by clicking Toggle Status. Click Add Module to add a new module that is already installed but not yet listed. Learn more about modules in Section 31.4, “Installing, Activating, and Configuring Modules”.

HTTP Server Configuration: Server Modules
Figure 31.4: HTTP Server Configuration: Server Modules
31.2.3.2.3 Main Host or Hosts

These dialogs are identical to the ones already described. Refer to Section 31.2.3.1.3, “Default Host” and Section 31.2.3.1.4, “Virtual Hosts”.

31.3 Starting and Stopping Apache

If configured with YaST as described in Section 31.2.3, “Configuring Apache with YaST”, Apache is started at boot time in the multi-user.target and graphical.target. You can change this behavior using YaST's Services Manager or with the systemctl command line tool (systemctl enable or systemctl disable).

To start, stop, or manipulate Apache on a running system, use either the systemctl or the apachectl commands as described below.

For general information about systemctl commands, refer to Section 13.2.1, “Managing Services in a Running System”.

systemctl status apache2

Checks if Apache is started.

systemctl start apache2

Starts Apache if it is not already running.

systemctl stop apache2

Stops Apache by terminating the parent process.

systemctl restart apache2

Stops and then restarts Apache. Starts the Web server if it was not running before.

systemctl try-restart apache2

Stops then restarts Apache only if it is already running.

systemctl reload apache2

Stops the Web server by advising all forked Apache processes to first finish their requests before shutting down. As each process dies, it is replaced by a newly started one, resulting in a complete restart of Apache.

Tip
Tip: Restarting Apache in Production Environments

This command allows activating changes in the Apache configuration without causing connection break-offs.

systemctl stop apache2

Stops the Web server after a defined period of time configured with GracefulShutdownTimeout to ensure that existing requests can be finished.

apachectl configtest

Checks the syntax of the configuration files without affecting a running Web server. Because this check is forced every time the server is started, reloaded, or restarted, it is usually not necessary to run the test explicitly (if a configuration error is found, the Web server is not started, reloaded, or restarted).

apachectl status and apachectl fullstatus

Dumps a short or full status screen, respectively. Requires the module mod_status to be enabled and a text-based browser (such as links or w3m) installed. In addition to that, status must be added to APACHE_SERVER_FLAGS in the file /etc/sysconfig/apache2.

Tip
Tip: Additional Flags

If you specify additional flags to the commands, these are passed through to the Web server.

31.4 Installing, Activating, and Configuring Modules

The Apache software is built in a modular fashion: all functionality except some core tasks are handled by modules. This has progressed so far that even HTTP is processed by a module (http_core).

Apache modules can be compiled into the Apache binary at build time or be dynamically loaded at runtime. Refer to Section 31.4.2, “Activation and Deactivation” for details of how to load modules dynamically.

Apache modules can be divided into four different categories:

Base Modules

Base modules are compiled into Apache by default. Apache in SUSE Linux Enterprise Server has only mod_so (needed to load other modules) and http_core compiled in. All others are available as shared objects: rather than being included in the server binary itself, they can be included at runtime.

Extension Modules

In general, modules labeled as extensions are included in the Apache software package, but are usually not compiled into the server statically. In SUSE Linux Enterprise Server, they are available as shared objects that can be loaded into Apache at runtime.

External Modules

Modules labeled external are not included in the official Apache distribution. However, SUSE Linux Enterprise Server provides several of them.

Multiprocessing Modules (MPMs)

MPMs are responsible for accepting and handling requests to the Web server, representing the core of the Web server software.

31.4.1 Module Installation

If you have done a default installation as described in Section 31.1.2, “Installation”, the following modules are already installed: all base and extension modules, the multiprocessing module Prefork MPM, and the external module mod_python.

You can install additional external modules by starting YaST and choosing Software › Software Management. Now choose View › Search and search for apache. Among other packages, the results list contains all available external Apache modules.

31.4.2 Activation and Deactivation

Activate or deactivate particular modules either manually or with YaST. In YaST, script language modules (PHP5, Perl, and Python) need to be enabled or disabled with the module configuration described in Section 31.2.3.1, “HTTP Server Wizard”. All other modules can be enabled or disabled as described in Section 31.2.3.2.2, “Server Modules”.

If you prefer to activate or deactivate the modules manually, use the commands a2enmod MODULE or a2dismod MODULE, respectively. a2enmod -l outputs a list of all currently active modules.

Important
Important: Including Configuration Files for External Modules

If you have activated external modules manually, make sure to load their configuration files in all virtual host configurations. Configuration files for external modules are located under /etc/apache2/conf.d/ and are loaded in /etc/apache2/default-server.conf by default. For more fine-grained control you can comment out the inclusion in /etc/apache2/default-server.conf and add it to specific virtual hosts only. See /etc/apache2/vhosts.d/vhost.template for examples.

31.4.3 Base and Extension Modules

All base and extension modules are described in detail in the Apache documentation. Only a brief description of the most important modules is available here. Refer to http://httpd.apache.org/docs/2.4/mod/ to learn details about each module.

mod_actions

Provides methods to execute a script whenever a certain MIME type (such as application/pdf), a file with a specific extension (like .rpm), or a certain request method (such as GET) is requested. This module is enabled by default.

mod_alias

Provides Alias and Redirect directives with which you can map a URl to a specific directory (Alias) or redirect a requested URL to another location. This module is enabled by default.

mod_auth*

The authentication modules provide different authentication methods: basic authentication with mod_auth_basic or digest authentication with mod_auth_digest.

mod_auth_basic and mod_auth_digest must be combined with an authentication provider module, mod_authn_* (for example, mod_authn_file for text file–based authentication) and with an authorization module mod_authz_* (for example, mod_authz_user for user authorization).

More information about this topic is available in the Authentication HOWTO at http://httpd.apache.org/docs/2.4/howto/auth.html.

mod_autoindex

Autoindex generates directory listings when no index file (for example, index.html) is present. The look and feel of these indexes is configurable. This module is enabled by default. However, directory listings are disabled by default via the Options directive—overwrite this setting in your virtual host configuration. The default configuration file for this module is located at /etc/apache2/mod_autoindex-defaults.conf.

mod_cgi

mod_cgi is needed to execute CGI scripts. This module is enabled by default.

mod_deflate

Using this module, Apache can be configured to compress given file types on the fly before delivering them.

mod_dir

mod_dir provides the DirectoryIndex directive with which you can configure which files are automatically delivered when a directory is requested (index.html by default). It also provides an automatic redirect to the correct URL when a directory request does not contain a trailing slash. This module is enabled by default.

mod_env

Controls the environment that is passed to CGI scripts or SSI pages. Environment variables can be set or unset or passed from the shell that invoked the httpd process. This module is enabled by default.

mod_expires

With mod_expires, you can control how often proxy and browser caches refresh your documents by sending an Expires header. This module is enabled by default.

mod_http2

With mod_http2, Apache gains support for the HTTP/2 protocol. It can be enabled by specifying Protocols h2 http/1.1 in a VirtualHost.

mod_include

mod_include lets you use Server Side Includes (SSI), which provide a basic functionality to generate HTML pages dynamically. This module is enabled by default.

mod_info

Provides a comprehensive overview of the server configuration under http://localhost/server-info/. For security reasons, you should always limit access to this URL. By default only localhost is allowed to access this URL. mod_info is configured at /etc/apache2/mod_info.conf.

mod_log_config

With this module, you can configure the look of the Apache log files. This module is enabled by default.

mod_mime

The mime module ensures that a file is delivered with the correct MIME header based on the file name's extension (for example text/html for HTML documents). This module is enabled by default.

mod_negotiation

Necessary for content negotiation. See http://httpd.apache.org/docs/2.4/content-negotiation.html for more information. This module is enabled by default.

mod_rewrite

Provides the functionality of mod_alias, but offers more features and flexibility. With mod_rewrite, you can redirect URLs based on multiple rules, request headers, and more.

mod_setenvif

Sets environment variables based on details of the client's request, such as the browser string the client sends, or the client's IP address. This module is enabled by default.

mod_spelling

mod_spelling attempts to automatically correct typographical errors in URLs, such as capitalization errors.

mod_ssl

Enables encrypted connections between Web server and clients. See Section 31.6, “Setting Up a Secure Web Server with SSL” for details. This module is enabled by default.

mod_status

Provides information on server activity and performance under http://localhost/server-status/. For security reasons, you should always limit access to this URL. By default, only localhost is allowed to access this URL. mod_status is configured at /etc/apache2/mod_status.conf.

mod_suexec

mod_suexec lets you run CGI scripts under a different user and group. This module is enabled by default.

mod_userdir

Enables user-specific directories available under ~USER/. The UserDir directive must be specified in the configuration. This module is enabled by default.

31.4.4 Multiprocessing Modules

SUSE Linux Enterprise Server provides two different multiprocessing modules (MPMs) for use with Apache:

31.4.4.1 Prefork MPM

The prefork MPM implements a non-threaded, preforking Web server. It makes the Web server behave similarly to Apache version 1.x. In this version it isolates each request and handles it by forking a separate child process. Thus problematic requests cannot affect others, avoiding a lockup of the Web server.

While providing stability with this process-based approach, the prefork MPM consumes more system resources than its counterpart, the worker MPM. The prefork MPM is considered the default MPM for Unix-based operating systems.

Important
Important: MPMs in This Document

This document assumes Apache is used with the prefork MPM.

31.4.4.2 Worker MPM

The worker MPM provides a multi-threaded Web server. A thread is a lighter form of a process. The advantage of a thread over a process is its lower resource consumption. Instead of only forking child processes, the worker MPM serves requests by using threads with server processes. The preforked child processes are multi-threaded. This approach makes Apache perform better by consuming fewer system resources than the prefork MPM.

One major disadvantage is the stability of the worker MPM: if a thread becomes corrupt, all threads of a process can be affected. In the worst case, this may result in a server crash. Especially when using the Common Gateway Interface (CGI) with Apache under heavy load, internal server errors might occur because of threads being unable to communicate with system resources. Another argument against using the worker MPM with Apache is that not all available Apache modules are thread-safe and thus cannot be used with the worker MPM.

Warning
Warning: Using PHP Modules with MPMs

Not all available PHP modules are thread-safe. Using the worker MPM with mod_php is strongly discouraged.

31.4.5 External Modules

Find a list of all external modules shipped with SUSE Linux Enterprise Server here. Find the module's documentation in the listed directory.

mod_apparmor

Adds support to Apache to provide AppArmor confinement to individual CGI scripts handled by modules like mod_php5 and mod_perl.

Package Name: apache2-mod_apparmor
More Information: Part IV, “Confining Privileges with AppArmor
mod_perl

mod_perl enables you to run Perl scripts in an embedded interpreter. The persistent interpreter embedded in the server avoids the overhead of starting an external interpreter and the penalty of Perl start-up time.

Package Name: apache2-mod_perl
Configuration File: /etc/apache2/conf.d/mod_perl.conf
More Information: /usr/share/doc/packages/apache2-mod_perl
mod_php5

PHP is a server-side, cross-platform HTML embedded scripting language.

Package Name: apache2-mod_php5
Configuration File: /etc/apache2/conf.d/php5.conf
More Information: /usr/share/doc/packages/apache2-mod_php5
mod_python

mod_python allows embedding Python within the Apache HTTP server for a considerable boost in performance and added flexibility in designing Web-based applications.

Package Name: apache2-mod_python
More Information: /usr/share/doc/packages/apache2-mod_python
mod_security

mod_security provides a Web application firewall to protect Web applications from a range of attacks. It also enables HTTP traffic monitoring and real-time analysis.

Package Name: apache2-mod_security2
Configuration File: /etc/apache2/conf.d/mod_security2.conf
More Information: /usr/share/doc/packages/apache2-mod_security2
Documentation: http://modsecurity.org/documentation/

31.4.6 Compilation

Apache can be extended by advanced users by writing custom modules. To develop modules for Apache or compile third-party modules, the package apache2-devel is required along with the corresponding development tools. apache2-devel also contains the apxs2 tools, which are necessary for compiling additional modules for Apache.

apxs2 enables the compilation and installation of modules from source code (including the required changes to the configuration files), which creates dynamic shared objects (DSOs) that can be loaded into Apache at runtime.

The apxs2 binaries are located under /usr/sbin:

  • /usr/sbin/apxs2—suitable for building an extension module that works with any MPM. The installation location is /usr/lib64/apache2.

  • /usr/sbin/apxs2-prefork—suitable for prefork MPM modules. The installation location is /usr/lib64/apache2-prefork.

  • /usr/sbin/apxs2-worker—suitable for worker MPM modules. The installation location is /usr/lib64/apache2-worker.

Install and activate a module from source code with the following commands:

cd /path/to/module/source
apxs2 -cia MODULE.c

where -c compiles the module, -i installs it, and -a activates it. Other options of apxs2 are described in the apxs2(1) man page.

31.5 Enabling CGI Scripts

Apache's Common Gateway Interface (CGI) lets you create dynamic content with programs or scripts usually called CGI scripts. CGI scripts can be written in any programming language. Usually, script languages such as Perl or PHP are used.

To enable Apache to deliver content created by CGI scripts, mod_cgi needs to be activated. mod_alias is also needed. Both modules are enabled by default. Refer to Section 31.4.2, “Activation and Deactivation” for details on activating modules.

Warning
Warning: CGI Security

Allowing the server to execute CGI scripts is a potential security hole. Refer to Section 31.8, “Avoiding Security Problems” for additional information.

31.5.1 Apache Configuration

In SUSE Linux Enterprise Server, the execution of CGI scripts is only allowed in the directory /srv/www/cgi-bin/. This location is already configured to execute CGI scripts. If you have created a virtual host configuration (see Section 31.2.2.1, “Virtual Host Configuration”) and want to place your scripts in a host-specific directory, you must unlock and configure this directory.

Example 31.5: VirtualHost CGI Configuration
ScriptAlias /cgi-bin/ "/srv/www/www.example.com/cgi-bin/"1

<Directory "/srv/www/www.example.com/cgi-bin/">
 Options +ExecCGI2
 AddHandler cgi-script .cgi .pl3
 Require all granted4
</Directory>

1

Tells Apache to handle all files within this directory as CGI scripts.

2

Enables CGI script execution

3

Tells the server to treat files with the extensions .pl and .cgi as CGI scripts. Adjust according to your needs.

4

The Require directive controls the default access state. In this case, access is granted to the specified directory without limitation. For more information on authentication and authorization, see http://httpd.apache.org/docs/2.4/howto/auth.html.

31.5.2 Running an Example Script

CGI programming differs from "regular" programming in that the CGI programs and scripts must be preceded by a MIME-Type header such as Content-type: text/html. This header is sent to the client, so it understands what kind of content it receives. Secondly, the script's output must be something the client, usually a Web browser, understands—HTML usually, or plain text or images, for example.

A simple test script available under /usr/share/doc/packages/apache2/test-cgi is part of the Apache package. It outputs the content of some environment variables as plain text. Copy this script to either /srv/www/cgi-bin/ or the script directory of your virtual host (/srv/www/www.example.com/cgi-bin/) and name it test.cgi. Edit the file to have #!/bin/sh as the first line.

Files accessible by the Web server should be owned by the user root. For additional information see Section 31.8, “Avoiding Security Problems”. Because the Web server runs with a different user, the CGI scripts must be world-executable and world-readable. Change into the CGI directory and use the command chmod 755 test.cgi to apply the proper permissions.

Now call http://localhost/cgi-bin/test.cgi or http://www.example.com/cgi-bin/test.cgi. You should see the CGI/1.0 test script report.

31.5.3 CGI Troubleshooting

If you do not see the output of the test program but an error message instead, check the following:

CGI Troubleshooting
  • Have you reloaded the server after having changed the configuration? If not, reload with systemctl reload apache2

  • If you have configured your custom CGI directory, is it configured properly? If in doubt, try the script within the default CGI directory /srv/www/cgi-bin/ and call it with http://localhost/cgi-bin/test.cgi.

  • Are the file permissions correct? Change into the CGI directory and execute ls -l test.cgi. The output should start with

    -rwxr-xr-x  1 root root
  • Make sure that the script does not contain programming errors. If you have not changed test.cgi, this should not be the case, but if you are using your own programs, always make sure that they do not contain programming errors.

31.6 Setting Up a Secure Web Server with SSL

Whenever sensitive data, such as credit card information, is transferred between Web server and client, it is desirable to have a secure, encrypted connection with authentication. mod_ssl provides strong encryption using the secure sockets layer (SSL) and transport layer security (TLS) protocols for HTTP communication between a client and the Web server. Using SSL/TLS, a private connection between Web server and client is established. Data integrity is ensured and client and server can authenticate each other.

For this purpose, the server sends an SSL certificate that holds information proving the server's valid identity before any request to a URL is answered. In turn, this guarantees that the server is the uniquely correct end point for the communication. Additionally, the certificate generates an encrypted connection between client and server that can transport information without the risk of exposing sensitive, plain-text content.

mod_ssl does not implement the SSL/TLS protocols itself, but acts as an interface between Apache and an SSL library. In SUSE Linux Enterprise Server, the OpenSSL library is used. OpenSSL is automatically installed with Apache.

The most visible effect of using mod_ssl with Apache is that URLs are prefixed with https:// instead of http://.

31.6.1 Creating an SSL Certificate

To use SSL/TLS with the Web server, you need to create an SSL certificate. This certificate is needed for the authorization between Web server and client, so that each party can clearly identify the other party. To ensure the integrity of the certificate, it must be signed by a party every user trusts.

There are three types of certificates you can create: a dummy certificate for testing purposes only, a self-signed certificate for a defined circle of users that trust you, and a certificate signed by an independent, publicly-known certificate authority (CA).

Creating a certificate is a two step process. First, a private key for the certificate authority is generated then the server certificate is signed with this key.

Tip
Tip: For More Information

To learn more about concepts and definitions of SSL/TLS, refer to http://httpd.apache.org/docs/2.4/ssl/ssl_intro.html.

31.6.1.1 Creating a Dummy Certificate

To generate a dummy certificate, call the script /usr/bin/gensslcert. It creates or overwrites the files listed below. Use gensslcert's optional switches to fine-tune the certificate. Call /usr/bin/gensslcert -h for more information.

  • /etc/apache2/ssl.crt/ca.crt

  • /etc/apache2/ssl.crt/server.crt

  • /etc/apache2/ssl.key/server.key

  • /etc/apache2/ssl.csr/server.csr

A copy of ca.crt is also placed at /srv/www/htdocs/CA.crt for download.

Important
Important: For Testing Purposes Only

A dummy certificate should never be used on a production system. Only use it for testing purposes.

31.6.1.2 Creating a Self-Signed Certificate

If you are setting up a secure Web server for an intranet or for a defined circle of users, it is probably sufficient if you sign a certificate with your own certificate authority (CA). Note that visitors to such a site will see a warning like this is an untrusted site, as Web browsers do not recognize self-signed certificates.

Important
Important: Self-Signed Certificates

Only use a self-signed certificate on a Web server that is accessed by people who know and trust you as a certificate authority. It is not recommended to use such a certificate for a public shop, for example.

First you need to generate a certificate signing request (CSR). You are going to use openssl, with PEM as the certificate format. During this step, you will be asked for a passphrase, and to answer several questions. Remember the passphrase you enter as you will need it in the future.

sudo openssl req -new > new.cert.csr
Generating a 1024 bit RSA private key
..++++++
.........++++++
writing new private key to 'privkey.pem'
Enter PEM pass phrase:1
Verifying - Enter PEM pass phrase:2
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:3
State or Province Name (full name) [Some-State]:4
Locality Name (eg, city) []:5
Organization Name (eg, company) [Internet Widgits Pty Ltd]:6
Organizational Unit Name (eg, section) []:7
Common Name (for example server FQDN, or YOUR name) []:8
Email Address []:9

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:10
An optional company name []:11

1

Fill in your passphrase,

2

...fill it in once more (and remember it).

3

Fill in your 2 letter country code, such as GB or CZ.

4

Fill in the name of the state where you live.

5

Fill in the city name, such as Prague.

6

Fill in the name of the organization you work for.

7

Fill in your organization unit, or leave blank if you have none.

8

Fill in either the domain name of the server, or your first and last name.

9

Fill in your work e-mail address.

10

Leave the challenge password empty, otherwise you will need to enter it every time you restart the Apache Web server.

11

Fill in the optional company name, or leave blank.

Now you can generate the certificate. You are going to use openssl again, and the format of the certificate is the default PEM.

Procedure 31.3: Generating the Certificate
  1. Export the private part of the key to new.cert.key. You will be prompted for the passphrase you entered when creating the certificate signing request (CSR).

    sudo openssl rsa -in privkey.pem -out new.cert.key
  2. Generate the public part of the certificate according to the information you filled out in the signing request. The -days option specifies the length of time before the certificate expires. You can revoke a certificate, or replace one before it expires.

    sudo openssl x509 -in new.cert.csr -out new.cert.cert -req \
    -signkey new.cert.key -days 365
  3. Copy the certificate files to the relevant directories, so that the Apache server can read them. Make sure that the private key /etc/apache2/ssl.key/server.key is not world-readable, while the public PEM certificate /etc/apache2/ssl.crt/server.crt is.

    sudo cp new.cert.cert /etc/apache2/ssl.crt/server.crt
    sudo cp new.cert.key /etc/apache2/ssl.key/server.key
Tip
Tip: Public Certificate Location

The last step is to copy the public certificate file from /etc/apache2/ssl.crt/server.crt to a location where your users can access it to incorporate it into the list of known and trusted CAs in their Web browsers. Otherwise a browser complains that the certificate was issued by an unknown authority.

31.6.1.3 Getting an Officially Signed Certificate

There are several official certificate authorities that sign your certificates. The certificate is signed by a trustworthy third party, so can be fully trusted. Publicly operating secure Web servers usually have an officially signed certificate. A list of the most used Certificate Authorities (CAs) is available at https://en.wikipedia.org/wiki/Certificate_authority#Providers.

When requesting an officially signed certificate, you do not send a certificate to the CA. Instead, issue a Certificate Signing Request (CSR). To create a CSR, run the following command:

openssl req -new -newkey rsa:2048 -nodes -keyout newkey.pem -out newreq.pem

You are asked to enter a distinguished name. This requires you to answer a few questions, such as country name or organization name. Enter valid data—everything you enter here later shows up in the certificate and is checked. You do not need to answer every question. If one does not apply to you or you want to leave it blank, use .. Common name is the name of the CA itself—choose a significant name, such as My company CA. Last, a challenge password and an alternative company name must be entered.

Find the CSR in the directory from which you called the script. The file is named newreq.pem.

31.6.2 Configuring Apache with SSL

The default port for SSL and TLS requests on the Web server side is 443. There is no conflict between a regular Apache listening on port 80 and an SSL/TLS-enabled Apache listening on port 443. In fact, HTTP and HTTPS can be run with the same Apache instance. Usually separate virtual hosts are used to dispatch requests to port 80 and port 443 to separate virtual servers.

Important
Important: Firewall Configuration

Do not forget to open the firewall for SSL-enabled Apache on port 443. This can be done with YaST as described in Section 15.4.1, “Configuring the Firewall with YaST”.

The SSL module is enabled by default in the global server configuration. In case it has been disabled on your host, activate it with the following command: a2enmod ssl. To finally enable SSL, the server needs to be started with the flag SSL. To do so, call a2enflag SSL (case-sensitive!). If you have chosen to encrypt your server certificate with a password, you should also increase the value for APACHE_TIMEOUT in /etc/sysconfig/apache2, so you have enough time to enter the passphrase when Apache starts. Restart the server to make these changes active. A reload is not sufficient.

The virtual host configuration directory contains a template /etc/apache2/vhosts.d/vhost-ssl.template with SSL-specific directives that are extensively documented. Refer to Section 31.2.2.1, “Virtual Host Configuration” for the general virtual host configuration.

To get started, copy the template to /etc/apache2/vhosts.d/MYSSL-HOST.conf and edit it. Adjusting the values for the following directives should be sufficient:

  • DocumentRoot

  • ServerName

  • ServerAdmin

  • ErrorLog

  • TransferLog

31.6.2.1 Name-Based Virtual Hosts and SSL

By default it is not possible to run multiple SSL-enabled virtual hosts on a server with only one IP address. Name-based virtual hosting requires that Apache knows which server name has been requested. The problem with SSL connections is, that such a request can only be read after the SSL connection has already been established (by using the default virtual host). As a result, users will receive a warning message stating that the certificate does not match the server name.

SUSE Linux Enterprise Server comes with an extension to the SSL protocol called Server Name Indication (SNI) addresses this issue by sending the name of the virtual domain as part of the SSL negotiation. This enables the server to switch to the correct virtual domain early and present the browser the correct certificate.

SNI is enabled by default on SUSE Linux Enterprise Server. To enable Name-Based Virtual Hosts for SSL, configure the server as described in Section 31.2.2.1.1, “Name-Based Virtual Hosts” (note that you need to use port 443 rather than port 80 with SSL).

Important
Important: SNI Browser Support

SNI must also be supported on the client side. However, SNI is supported by most browsers, except for certain older browsers. For more information, see https://en.wikipedia.org/wiki/Server_Name_Indication#Support.

To configure handling of non-SNI capable browsers, use the directive SSLStrictSNIVHostCheck. When set to on in the server configuration, non-SNI capable browser will be rejected for all virtual hosts. When set to on within a VirtualHost directive, access to this particular host will be rejected.

When set to off in the server configuration, the server will behave as if not having SNI support. SSL requests will be handled by the first virtual host defined (for port 443).

31.7 Running Multiple Apache Instances on the Same Server

As of SUSE® Linux Enterprise Server 12 SP1, you can run multiple Apache instances on the same server. This has several advantages over running multiple virtual hosts (see Section 31.2.2.1, “Virtual Host Configuration”):

  • When a virtual host needs to be disabled for some time, you need to change the Web server configuration and restart it so that the change takes effect.

  • In case of problems with one virtual host, you need to restart all of them.

You can run the default Apache instance as usual:

sytemctl start apache2

It reads the default /etc/sysconfig/apache2 file. If the file is not present, or it is present but it does not set the APACHE_HTTPD_CONF variable, it reads /etc/apache2/httpd.conf.

To activate another Apache instance, run:

systemctl start apache2@INSTANCE_NAME

For example:

systemctl start apache2@example_web.org

By default, the instance uses /etc/apache2@example_web.org/httpd.conf as a main configuration file, which can be overwritten by setting APACHE_HTTPD_CONF in /etc/sysconfig/apache2@example_web.org.

An example to set up an additional instance of Apache follows. Note that you need to execute all the commands as root.

Procedure 31.4: Configuring an Additional Apache Instance
  1. Create a new configuration file based on /etc/sysconfig/apache2, for example /etc/sysconfig/apache2@example_web.org:

    cp /etc/sysconfig/apache2 /etc/sysconfig/apache2@example_web.org
  2. Edit the file /etc/sysconfig/apache2@example_web.org and change the line containing

    APACHE_HTTPD_CONF

    to

    APACHE_HTTPD_CONF="/etc/apache2/httpd@example_web.org.conf"
  3. Create the file /etc/apache2/httpd@example_web.org.conf based on /etc/apache2/httpd.conf.

    cp /etc/apache2/httpd.conf /etc/apache2/httpd@example_web.org.conf
  4. Edit /etc/apache2/httpd@example_web.org.conf and change

    Include /etc/apache2/listen.conf

    to

    Include /etc/apache2/listen@example_web.org.conf

    Review all the directives and change them to fit your needs. You will probably want to change

    Include /etc/apache2/global.conf

    and create new global@example_web.org.conf for each instance. We suggest to change

    ErrorLog /var/log/apache2/error_log

    to

    ErrorLog /var/log/apache2/error@example_web.org_log

    to have separate logs for each instance.

  5. Create /etc/apache2/listen@example_web.org.conf based on /etc/apache2/listen.conf.

    cp /etc/apache2/listen.conf /etc/apache2/listen@example_web.org.conf
  6. Edit /etc/apache2/listen@example_web.org.conf and change

    Listen 80

    to the port number you want the new instance to run on, for example 82:

    Listen 82

    To run the new Apache instance over a secured protocol (see Section 31.6, “Setting Up a Secure Web Server with SSL”), change also the line

    Listen 443

    for example to

    Listen 445
  7. Start the new Apache instance:

    systemctl start apache2@example_web.org
  8. Check if the server is running by pointing your Web browser at http://server_name:82. If you previously changed the name of the error log file for the new instance, you can check it:

    tail -f /var/log/apache2/error@example_web.org_log

Here are several points to consider when setting up more Apache instances on the same server:

  • The file /etc/sysconfig/apache2@INSTANCE_NAME can include the same variables as /etc/sysconfig/apache2, including module loading and MPM setting.

  • The default Apache instance does not need to be running while other instances run.

  • The Apache helper utilities a2enmod, a2dismod and apachectl operate on the default Apache instance if not specified otherwise with the HTTPD_INSTANCE environment variable. The following example

    export HTTPD_INSTANCE=example_web.org
    a2enmod access_compat
    a2enmod status
    apachectl start

    will add access_compat and status modules to the APACHE_MODULES variable of /etc/sysconfig/apache2@example_web.org, and then start the example_web.org instance.

31.8 Avoiding Security Problems

A Web server exposed to the public Internet requires an ongoing administrative effort. It is inevitable that security issues appear, both related to the software and to accidental misconfiguration. Here are some tips for how to deal with them.

31.8.1 Up-to-Date Software

If there are vulnerabilities found in the Apache software, a security advisory will be issued by SUSE. It contains instructions for fixing the vulnerabilities, which in turn should be applied when possible. The SUSE security announcements are available from the following locations:

31.8.2 DocumentRoot Permissions

By default in SUSE Linux Enterprise Server, the DocumentRoot directory /srv/www/htdocs and the CGI directory /srv/www/cgi-bin belong to the user and group root. You should not change these permissions. If the directories are writable for all, any user can place files into them. These files might then be executed by Apache with the permissions of wwwrun, which may give the user unintended access to file system resources. Use subdirectories of /srv/www to place the DocumentRoot and CGI directories for your virtual hosts and make sure that directories and files belong to user and group root.

31.8.3 File System Access

By default, access to the whole file system is denied in /etc/apache2/httpd.conf. You should never overwrite these directives, but specifically enable access to all directories Apache should be able to read. For details, see Section 31.2.2.1.3, “Basic Virtual Host Configuration”. In doing so, ensure that no critical files, such as password or system configuration files, can be read from the outside.

31.8.4 CGI Scripts

Interactive scripts in Perl, PHP, SSI, or any other programming language can essentially run arbitrary commands and therefore present a general security issue. Scripts that will be executed from the server should only be installed from sources the server administrator trusts—allowing users to run their own scripts is generally not a good idea. It is also recommended to do security audits for all scripts.

To make the administration of scripts as easy as possible, it is common practice to limit the execution of CGI scripts to specific directories instead of globally allowing them. The directives ScriptAlias and Option ExecCGI are used for configuration. The SUSE Linux Enterprise Server default configuration does not allow execution of CGI scripts from everywhere.

All CGI scripts run as the same user, so different scripts can potentially conflict with each other. The module suEXEC lets you run CGI scripts under a different user and group.

31.8.5 User Directories

When enabling user directories (with mod_userdir or mod_rewrite) you should strongly consider not allowing .htaccess files, which would allow users to overwrite security settings. At least you should limit the user's engagement by using the directive AllowOverRide. In SUSE Linux Enterprise Server, .htaccess files are enabled by default, but the user is not allowed to overwrite any Option directives when using mod_userdir (see the /etc/apache2/mod_userdir.conf configuration file).

31.9 Troubleshooting

If Apache does not start, the Web page is not accessible, or users cannot connect to the Web server, it is important to find the cause of the problem. Here are some typical places to look for error explanations and important things to check:

Output of the apache2.service subcommand:

Instead of starting and stopping the Web server with the binary /usr/sbin/apache2ctl, rather use the systemctl commands instead (described in Section 31.3, “Starting and Stopping Apache”). systemctl status apache2 is verbose about errors, and it even provides tips and hints for fixing configuration errors.

Log Files and Verbosity

In case of both fatal and nonfatal errors, check the Apache log files for causes, mainly the error log file located at /var/log/apache2/error_log by default. Additionally, you can control the verbosity of the logged messages with the LogLevel directive if more detail is needed in the log files.

Tip
Tip: A Simple Test

Watch the Apache log messages with the command tail -F /var/log/apache2/MY_ERROR_LOG. Then run systemctl restart apache2. Now, try to connect with a browser and check the output.

Firewall and Ports

A common mistake is to not open the ports for Apache in the firewall configuration of the server. If you configure Apache with YaST, there is a separate option available to take care of this specific issue (see Section 31.2.3, “Configuring Apache with YaST”). If you are configuring Apache manually, open firewall ports for HTTP and HTTPS via YaST's firewall module.

If the error cannot be tracked down with any of these, check the online Apache bug database at http://httpd.apache.org/bug_report.html. Additionally, the Apache user community can be reached via a mailing list available at http://httpd.apache.org/userslist.html.

31.10 For More Information

The package apache2-doc contains the complete Apache manual in various localizations for local installation and reference. It is not installed by default—the quickest way to install it is to use the command zypper in apache2-doc. having been installed, the Apache manual is available at http://localhost/manual/. You may also access it on the Web at http://httpd.apache.org/docs-2.4/. SUSE-specific configuration hints are available in the directory /usr/share/doc/packages/apache2/README.*.

31.10.1 Apache 2.4

For a list of new features in Apache 2.4, refer to http://httpd.apache.org/docs/2.4/new_features_2_4.html. Information about upgrading from version 2.2 to 2.4 is available at http://httpd.apache.org/docs-2.4/upgrading.html.

31.10.2 Apache Modules

More information about external Apache modules that are briefly described in Section 31.4.5, “External Modules” is available at the following locations:

31.10.3 Development

More information about developing Apache modules or about getting involved in the Apache Web server project are available at the following locations:

Apache Developer Information

http://httpd.apache.org/dev/

Apache Developer Documentation

http://httpd.apache.org/docs/2.4/developer/

Writing Apache Modules with Perl and C

http://www.modperl.com/

31.10.4 Miscellaneous Sources

If you experience difficulties specific to Apache in SUSE Linux Enterprise Server, take a look at the Technical Information Search at http://www.suse.com/support. The history of Apache is provided at http://httpd.apache.org/ABOUT_APACHE.html. This page also explains why the server is called Apache.

32 Setting Up an FTP Server with YaST

  • Filename: yast2_ftp.xml
  • ID: cha.ftp
Abstract

Using the YaST FTP Server module, you can configure your machine to function as an FTP (File Transfer Protocol) server. Anonymous and/or authenticated users can connect to your machine and download files using the FTP protocol. Depending on the configuration, they can also upload files to the FTP server. YaST uses vsftpd (Very Secure FTP Daemon).

If the YaST FTP Server module is not available in your system, install the yast2-ftp-server package.

To configure the FTP server using YaST, follow these steps:

  1. Open the YaST control center and choose Network Services › FTP Server or run the yast2 ftp-server command as root.

  2. If there is not any FTP server installed in your system, you will be asked which server to install when the YaST FTP Server module starts. Choose the vsftpd server and confirm the dialog.

  3. In the Start-Up dialog, configure the options for starting of the FTP server. For more information, see Section 32.1, “Starting the FTP Server”.

    In the General dialog, configure FTP directories, welcome message, file creation masks and other parameters. For more information, see Section 32.2, “FTP General Settings”.

    In the Performance dialog, set the parameters that affect the load on the FTP server. For more information, see Section 32.3, “FTP Performance Settings”.

    In the Authentication dialog, set whether the FTP server should be available for anonymous and/or authenticated users. For more information, see Section 32.4, “Authentication”.

    In the Expert Settings dialog, configure the operation mode of the FTP server, SSL connections and firewall settings. For more information, see Section 32.5, “Expert Settings”.

  4. Press Finish to save the configurations.

32.1 Starting the FTP Server

In the Service Start frame of the FTP Start-Up dialog set the way the FTP server is started up. You can choose between starting the server automatically during the system boot and starting it manually. If the FTP server should be started only after an FTP connection request, choose Via xinetd.

The current status of the FTP server is shown in the Switch On and Off frame of the FTP Start-Up dialog. Start the FTP server by clicking Start FTP Now. To stop the server, click Stop FTP Now. After having changed the settings of the server click Save Settings and Restart FTP Now. Your configurations will be saved by leaving the configuration module with Finish.

The Selected Service frame of the FTP Start-Up dialog shows which FTP server is used: either vsftpd or pure-ftpd. If both servers are installed, you can switch between them—the current configuration will automatically be converted.

FTP Server Configuration — Start-Up
Figure 32.1: FTP Server Configuration — Start-Up

32.2 FTP General Settings

In the General Settings frame of the FTP General Settings dialog you can set the Welcome message which is shown after connecting to the FTP server.

If you check the Chroot Everyone option, all local users will be placed in a chroot jail in their home directory after login. This option has security implications, especially if the users have upload permission or shell access, so be careful enabling this option.

If you check the Verbose Logging option, all FTP requests and responses are logged.

You can limit permissions of files created by anonymous and/or authenticated users with umask. Set the file creation mask for anonymous users in Umask for Anonymous and the file creation mask for authenticated users in Umask for Authenticated Users. The masks should be entered as octal numbers with a leading zero. For more information about umask, see the umask man page (man 1p umask).

In the FTP Directories frame set the directories used for anonymous and authorized users. With Browse, you can select a directory to be used from the local file system. The default FTP directory for anonymous users is /srv/ftp. Note that vsftpd does not allow this directory to be writable for all users. The subdirectory upload with write permissions for anonymous users is created instead.

Note
Note: Write Permissions in FTP Directory

The pure-ftpd server allows the FTP directory for anonymous users to be writable. When switching between servers, make sure you remove the write permissions in the directory that was used with pure-ftpd before switching back to the vsftpd server.

32.3 FTP Performance Settings

In the Performance dialog set the parameters which affect the load on the FTP server. Max Idle Time is the maximum time (in minutes) the remote client may spend between FTP commands. In case of longer inactivity, the remote client is disconnected. Max Clients for One IP determines the maximum number of clients which can be connected from a single IP address. Max Clients determines the maximum number of clients which may be connected. Any additional clients will get an error message.

The maximum data transfer rate (in KB/s) is set in Local Max Rate for local authenticated users, and in Anonymous Max Rate for anonymous clients respectively. The default value for the rate settings is 0, which means unlimited data transfer rate.

32.4 Authentication

In the Enable/Disable Anonymous and Local Users frame of the Authentication dialog, you can set which users are allowed to access your FTP server. You can choose between the following options: granting access to anonymous users only, to authenticated users only (with accounts on the system) or to both types of users.

To allow users to upload files to the FTP server, check Enable Upload in the Uploading frame of the Authentication dialog. Here you can allow uploading or creating directories even for anonymous users by checking the respective box.

Note
Note: vsftp—Allowing File Upload for Anonymous Users

If a vsftpd server is used and you want anonymous users to be able to upload files or create directories, a subdirectory with writing permissions for all users needs to be created in the anonymous FTP directory.

32.5 Expert Settings

An FTP server can run in active or in passive mode. By default the server runs in passive mode. To switch into active mode, uncheck Enable Passive Mode option in Expert Settings dialog. You can also change the range of ports on the server used for the data stream by tweaking the Min Port for Pas. Mode and Max Port for Pas. Mode options.

If you want encrypted communication between clients and the server, you can Enable SSL. Check the versions of the protocol to be supported and specify the DSA certificate to be used for SSL encrypted connections.

If your system is protected by a firewall, check Open Port in Firewall to enable a connection to the FTP server.

32.6 For More Information

For more information about the FTP server read the manual pages of vsftpd and vsftpd.conf.

33 The Proxy Server Squid

  • Filename: net_proxy.xml
  • ID: cha.squid
Abstract

Squid is a widely-used proxy cache for Linux and Unix platforms. This means that it stores requested Internet objects, such as data on a Web or FTP server, on a machine that is closer to the requesting workstation than the server. It can be set up in multiple hierarchies to assure optimal response times and low bandwidth usage, even in modes that are transparent to end users. Additional software like squidGuard can be used to filter Web content.

Squid acts as a proxy cache. It redirects object requests from clients (in this case, from Web browsers) to the server. When the requested objects arrive from the server, it delivers the objects to the client and keeps a copy of them in the hard disk cache. An advantage of caching is that several clients requesting the same object can be served from the hard disk cache. This enables clients to receive the data much faster than from the Internet. This procedure also reduces the network traffic.

Along with actual caching, Squid offers a wide range of features:

  • Distributing load over intercommunicating hierarchies of proxy servers

  • Defining strict access control lists for all clients accessing the proxy

  • Allowing or denying access to specific Web pages using other applications

  • Generating statistics about frequently-visited Web pages for the assessment of surfing habits

Squid is not a generic proxy. It normally proxies only HTTP connections. It supports the protocols FTP, Gopher, SSL, and WAIS, but it does not support other Internet protocols, such as the news protocol, or video conferencing protocols. Because Squid only supports the UDP protocol to provide communication between different caches, many multimedia programs are not supported.

33.1 Some Facts about Proxy Caches

As a proxy cache, Squid can be used in several ways. When combined with a firewall, it can help with security. Multiple proxies can be used together. It can also determine what types of objects should be cached and for how long.

33.1.1 Squid and Security

It is possible to use Squid together with a firewall to secure internal networks from the outside using a proxy cache. The firewall denies all clients access to external services except Squid. All Web connections must be established by the proxy. With this configuration, Squid completely controls Web access.

If the firewall configuration includes a DMZ, the proxy should operate within this zone. Section 33.6, “Configuring a Transparent Proxy” describes how to implement a transparent proxy. This simplifies the configuration of the clients, because in this case, they do not need any information about the proxy.

33.1.2 Multiple Caches

Several instances of Squid can be configured to exchange objects between them. This reduces the total system load and increases the chances of retrieving an object from the local network. It is also possible to configure cache hierarchies, so a cache can forward object requests to sibling caches or to a parent cache—causing it to request objects from another cache in the local network or directly from the source.

Choosing the appropriate topology for the cache hierarchy is very important, because it is not desirable to increase the overall traffic on the network. For a very large network, it would make sense to configure a proxy server for every subnet and connect them to a parent proxy, which in turn is connected to the proxy cache of the ISP.

All this communication is handled by ICP (Internet cache protocol) running on top of the UDP protocol. Data transfers between caches are handled using HTTP (hypertext transmission protocol) based on TCP.

To find the most appropriate server from which to request objects, a cache sends an ICP request to all sibling proxies. The sibling proxies answer these requests via ICP responses. If the object was detected, they use the code HIT, if not, they use MISS.

If multiple HIT responses were found, the proxy server decides from which server to download, depending on factors such as which cache sent the fastest answer or which one is closer. If no satisfactory responses are received, the request is sent to the parent cache.

Note
Note: How Squid Avoids Duplication of Objects

To avoid duplication of objects in different caches in the network, other ICP protocols are used, such as CARP (cache array routing protocol) or HTCP (hypertext cache protocol). The more objects maintained in the network, the greater the possibility of finding the desired one.

33.1.3 Caching Internet Objects

Many objects available in the network are not static, such as dynamically generated pages and TLS/SSL-encrypted content. Objects like these are not cached because they change each time they are accessed.

To determine how long objects should remain in the cache, objects are assigned one of several states. Web and proxy servers find out the status of an object by adding headers to these objects, such as Last modified or Expires and the corresponding date. Other headers specifying that objects must not be cached can be used as well.

Objects in the cache are normally replaced, because of a lack of free disk space, using algorithms such as LRU (last recently used). This means that the proxy expunges those objects that have not been requested for the longest time.

33.2 System Requirements

System requirements largely depend on the maximum network load that the system must bear. Therefore, examine load peaks, as during those times, load might be more than four times the day's average. When in doubt, slightly overestimate the system's requirements. Having Squid working close to the limit of its capabilities can lead to a severe loss in quality of service. The following sections point to system factors in order of significance:

  1. RAM size

  2. CPU speed/physical CPU cores

  3. Size of the disk cache

  4. Hard disks/SSDs and their architecture

33.2.1 RAM

The amount of memory (RAM) required by Squid directly correlates with the number of objects in the cache. Random access memory is much faster than a hard disk/SSD. Therefore, it is very important to have sufficient memory for the Squid process, because system performance is dramatically reduced if the swap disk is used.

Squid also stores cache object references and frequently requested objects in the main memory to speed up retrieval of this data. In addition to that, there is other data that Squid needs to keep in memory, such as a table with all the IP addresses handled, an exact domain name cache, the most frequently requested objects, access control lists, buffers, and more.

33.2.2 CPU

Squid is tuned to work best with lower processor core counts (4–8 physical cores), with each providing high performance. Technologies providing virtual cores such as hyperthreading can hurt performance.

To make the best use of multiple CPU cores, it is necessary to set up multiple worker threads writing to different caching devices. By default, multi-core support is mostly disabled.

33.2.3 Size of the Disk Cache

In a small cache, the probability of a HIT (finding the requested object already located there) is small, because the cache is easily filled and less requested objects are replaced by newer ones. If, for example, 1 GB is available for the cache and the users use up only 10 MB per day surfing, it would take more than one hundred days to fill the cache.

The easiest way to determine the necessary cache size is to consider the maximum transfer rate of the connection. With a 1 Mbit/s connection, the maximum transfer rate is 128 KB/s. If all this traffic ended up in the cache, in one hour it would add up to 460 MB. Assuming that all this traffic is generated in only eight working hours, it would reach 3.6 GB in one day. Because the connection is normally not used to its upper volume limit, it can be assumed that the total data volume handled by the cache is approximately 2 GB. Hence, in this example, 2 GB of disk space is required for Squid to keep one day's worth of browsing data cached.

33.2.4 Hard Disk/SSD Architecture

Speed plays an important role in the caching process, so this factor deserves special attention. For hard disks/SSDs, this parameter is described as random seek time or random read performance, measured in milliseconds. Because the data blocks that Squid reads from or writes to the hard disk/SSD tend to be small, the seek time/read performance of the hard disk/SSD is more important than its data throughput.

For use as a proxy, hard disks with high rotation speeds or SSDs are the best choice. When using hard disks, it can be better to use multiple smaller hard disks, each with a single cache directory to avoid excessive read times.

Using a RAID system allows increasing reliability at expense of speed. However, for performance reasons, avoid (software) RAID5 and similar settings.

File system choice is usually not decisive. However, using the mount option noatime can improve performance—Squid provides its own time stamps and thus does not need the file system to track access times.

33.3 Basic Usage of Squid

If not already installed, install the package squid . squid is not among the packages installed by default on SUSE® Linux Enterprise Server.

Squid is already preconfigured in SUSE Linux Enterprise Server, you can start it directly after the installation. To ensure a smooth start-up, the network should be configured in a way that at least one name server and the Internet can be reached. Problems can arise if a dial-up connection is used with a dynamic DNS configuration. In this case, at least the name server should be specified, because Squid does not start if it does not detect a DNS server in /etc/resolv.conf.

33.3.1 Starting Squid

To start Squid, use:

tux > sudo systemctl start squid

If you want Squid to start together with the system, enable the service with systemctl enable squid.

33.3.2 Checking Whether Squid Is Working

To check whether Squid is running, choose one of the following ways:

  • Using systemctl:

    tux > systemctl status squid

    The output of this command should indicate that Squid is loaded and active (running).

  • Using Squid itself:

    tux > sudo squid -k check | echo $?

    The output of this command should be 0, but may contain additional warnings or messages.

To test the functionality of Squid on the local system, choose one of the following ways:

  • To test, you can use squidclient, a command-line tool that can output the response to a Web request, similar to wget or curl.

    Unlike those tools, squidclient will automatically connect to the default proxy setup of Squid, localhost:3128. However, if you changed the configuration of Squid, you need to configure squidclient to use different settings using command line options. For more information, see squidclient --help.

    Example 33.1: A Request With squidclient
    tux > squidclient http://www.example.org
    HTTP/1.1 200 OK
    Cache-Control: max-age=604800
    Content-Type: text/html
    Date: Fri, 22 Jun 2016 12:00:00 GMT
    Expires: Fri, 29 Jun 2016 12:00:00 GMT
    Last-Modified: Fri, 09 Aug 2013 23:54:35 GMT
    Server: ECS (iad/182A)
    Vary: Accept-Encoding
    X-Cache: HIT
    x-ec-custom-error: 1
    Content-Length: 1270
    X-Cache: MISS from moon1
    X-Cache-Lookup: MISS from moon:3128
    Via: 1.1 moon (squid/3.5.16)2
    Connection: close
    
    <!doctype html>
    <html>
    <head>
        <title>Example Domain</title>
    [...]
    </body>
    </html>

    The output shown in Example 33.1, “A Request With squidclient can be split into two parts:

    1. The protocol headers of the response: the lines before the blank line.

    2. The actual content of the response: the lines after the blank line.

    To verify that Squid is used, refer to the selected header lines:

    1

    The value of the header X-Cache tells you that the requested document was not in the Squid cache (MISS) of the computer moon.

    The example above contains two X-Cache lines. You can ignore the first X-Cache header. It is produced by the internal caching software of the originating Web server.

    2

    The value of the header Via tells you the HTTP version, the name of the computer, and the version of Squid in use.

  • Using a browser: Set up localhost as the proxy and 3128 as the port. You can then load a page and check the response headers in the Network panel of the browser's Inspector or Developer Tools. The headers should be reproduced similarly to the way shown in Example 33.1, “A Request With squidclient.

To allow users from the local system and other systems to access Squid and the Internet, change the entry in the configuration files /etc/squid/squid.conf from http_access deny all to http_access allow all. However, in doing so, consider that Squid is made completely accessible to anyone by this action. Therefore, define ACLs (access control lists) that control access to the proxy. After modifying the configuration file, Squid must be reloaded or restarted. For more information on ACLs, see Section 33.5.2, “Options for Access Controls”.

If Squid quits after a short period of time even though it was started successfully, check whether there is a faulty name server entry or whether the /etc/resolv.conf file is missing. Squid logs the cause of a start-up failure in the file /var/log/squid/cache.log.

33.3.3 Stopping, Reloading, and Restarting Squid

To reload Squid, choose one of the following ways:

  • Using systemctl:

    root # systemctl reload squid

    or

    root # systemctl restart squid
  • Using YaST:

    In the Squid module, click the Save Settings and Restart Squid Now. button.

To stop Squid, choose one of the following ways:

  • Using systemctl:

    root # systemctl stop squid
  • Using YaST

    In the Squid module click the Stop Squid Now. button.

Shutting down Squid can take a while, because Squid waits up to half a minute before dropping the connections to the clients and writing its data to the disk (see shutdown_lifetime option in /etc/squid/squid.conf),

Warning
Warning: Terminating Squid

Terminating Squid with kill or killall can damage the cache. To be able to restart Squid, damaged caches must be deleted.

33.3.4 Removing Squid

Removing Squid from the system does not remove the cache hierarchy and log files. To remove these, delete the /var/cache/squid directory manually.

33.3.5 Local DNS Server

Setting up a local DNS server makes sense even if it does not manage its own domain. It then simply acts as a caching-only name server and is also able to resolve DNS requests via the root name servers without requiring any special configuration (see Section 25.4, “Starting the BIND Name Server”). How this can be done depends on whether you chose dynamic DNS during the configuration of the Internet connection.

Dynamic DNS

Normally, with dynamic DNS, the DNS server is set by the provider during the establishment of the Internet connection and the local /etc/resolv.conf file is adjusted automatically. This behavior is controlled in the /etc/sysconfig/network/config file with the NETCONFIG_DNS_POLICY sysconfig variable. Set NETCONFIG_DNS_POLICY to "" with the YaST sysconfig editor.

Then, add the local DNS server in the /etc/resolv.conf file with the IP address 127.0.0.1 for localhost. This way, Squid can always find the local name server when it starts.

To make the provider's name server accessible, specify it in the configuration file /etc/named.conf under forwarders along with its IP address. With dynamic DNS, this can be achieved automatically when establishing the connection by setting the sysconfig variable NETCONFIG_DNS_POLICY to auto.

Static DNS

With static DNS, no automatic DNS adjustments take place while establishing a connection, so there is no need to change any sysconfig variables. However, you must specify the local DNS server in the file /etc/resolv.conf as described in Dynamic DNS. Additionally, the provider's static name server must be specified manually in the /etc/named.conf file under forwarders along with its IP address.

Tip
Tip: DNS and Firewall

If you have a firewall running, make sure DNS requests can pass it.

33.4 The YaST Squid Module

The YaST Squid module contains the following tabs:

Start-Up

Specifies how Squid is started and which Firewall port is open on which interfaces.

HTTP Ports

Define all ports where Squid will listen for clients' http requests.

Refresh Patterns

Defines how Squid treats objects in the cache.

Cache Settings

Defines settings in regard to cache memory, maximum and minimum object size, and more.

Cache Directory

Defines the top-level directory where Squid stores all cache swap files.

Access Control

Controls the access to the Squid server via ACL groups.

Logging and Timeout

Define paths to access, cache, and cache store log files in addition with connection timeouts and client lifetime.

Miscellaneous

Sets language and mail address of administrator.

33.5 The Squid Configuration File

All Squid proxy server settings are made in the /etc/squid/squid.conf file. To start Squid for the first time, no changes are necessary in this file, but external clients are initially denied access. The proxy is available for localhost. The default port is 3128. The preinstalled configuration file /etc/squid/squid.conf provides detailed information about the options and many examples.

Many entries are commented and therefore begin with the comment character #. The relevant specifications can be found at the end of the line. The given values usually correlate with the default values, so removing the comment signs without changing any of the parameters usually has no effect. If possible, leave the commented lines as they are and insert the options along with the modified values in the line below. This way, the default values may easily be recovered and compared with the changes.

Tip
Tip: Adapting the Configuration File After an Update

If you have updated from an earlier Squid version, it is recommended to edit the new /etc/squid/squid.conf and only apply the changes made in the previous file.

Sometimes, Squid options are added, removed, or modified. Therefore, if you try to use the old squid.conf, Squid might stop working properly.

33.5.1 General Configuration Options

The following is a list of a selection of configuration options for Squid. It is not exhaustive. The Squid package contains a full, lightly documented list of options in /etc/squid/squid.conf.documented.

http_port PORT

This is the port on which Squid listens for client requests. The default port is 3128, but 8080 is also common.

cache_peer HOST_NAME TYPE PROXY_PORT ICP_PORT

This option allows creating a network of caches that work together. The cache peer is a computer that also hosts a network cache and stands in a relationship to your own. The type of relationship is specified as the TYPE. The type can either be parent or sibling.

As the HOST_NAME, specify the name or IP address of the proxy to use. For PROXY_PORT, specify the port number for use in a browser (usually 8080). Set ICP_PORT to 7 or, if the ICP port of the parent is not known and its use is irrelevant to the provider, to 0.

To make Squid behave like a Web browser instead of like a proxy, prohibit the use of the ICP protocol. You can do so by appending the options default and no-query.

cache_mem SIZE

This option defines the amount of memory Squid can use for very popular replies. The default is 8 MB. This does not specify the memory usage of Squid and may be exceeded.

cache_dir STORAGE_TYPE CACHE_DIRECTORY CACHE_SIZE LEVEL_1_DIRECTORIES LEVEL_2_DIRECTORIES

The option cache_dir defines the directory for the disk cache. In the default configuration on SUSE Linux Enterprise Server, Squid does not create a disk cache.

The placeholder STORAGE_TYPE can be one of the following:

  • Directory-based storage types: ufs, aufs (the default), diskd. All three are variations of the storage format ufs. However, while ufs runs as part of the core Squid thread, aufs runs in a separate thread, and diskd uses a separate process. This means that the latter two types avoid blocking Squid because of disk I/O.

  • Database-based storage systems: rock. This storage format relies on a single database file, in which each object takes up one or more memory units of a fixed size (slots).

In the following, only the parameters for storage types based on ufs will be discussed. rock has somewhat different parameters.

The CACHE_DIRECTORY is the directory for the disk cache. By default, that is /var/cache/squid. CACHE_SIZE is the maximum size of that directory in megabytes; by default, this is set to 100 MB. Set it to between 50% and a maximum of 80% of available disk space.

The final two values, LEVEL_1_DIRECTORIES and LEVEL_2_DIRECTORIES specify how many subdirectories are created in the CACHE_DIRECTORY. By default, 16 subdirectories are created at the first level below CACHE_DIRECTORY and 256 within each of these. These values should only be increased with caution, because creating too many directories can lead to performance problems.

If you have several disks that share a cache, specify several cache_dir lines.

cache_access_log LOG_FILE , cache_log LOG_FILE , cache_store_log LOG_FILE

These three options specify the paths where Squid logs all its actions. Normally, nothing needs to be changed here. If Squid is burdened by heavy usage, it might make sense to distribute the cache and the log files over several disks.

client_netmask NETMASK

This option allows masking IP addresses of clients in the log files by applying a subnet mask. For example, to set the last digit of the IP address to 0, specify 255.255.255.0.

ftp_user E-MAIL

This option allows setting the password that Squid should use for anonymous FTP login. Specify a valid e-mail address here, because some FTP servers check these for validity.

cache_mgr E-MAIL

If it unexpectedly crashes, Squid sends a message to this e-mail address. The default is webmaster.

logfile_rotate VALUE

If you run squid -k rotate, Squid can rotate log files. The files are numbered in this process and, after reaching the specified value, the oldest file is overwritten. The default value is 10 which rotates log files with the numbers 0 to 9.

However, on SUSE Linux Enterprise Server, rotating log files is performed automatically using logrotate and the configuration file /etc/logrotate.d/squid.

append_domain DOMAIN

Use append_domain to specify which domain to append automatically when none is given. Usually, your own domain is specified here, so specifying www in the browser accesses your own Web server.

forwarded_for STATE

If this option is set to on, it adds a line to the header similar to this:

X-Forwarded-For: 192.168.0.1

If you set this option to off, Squid removes the IP address and the system name of the client from HTTP requests.

negative_ttl TIME , negative_dns_ttl TIME

If these options are set, Squid will cache some types of failures, such as 404 responses. It will then refuse to issue new requests, even if the resource would be available then.

By default, negative_ttl is set to 0, negative_dns_ttl is set to 1 minutes. This means that negative responses to Web requests are not cached by default, while negative responses to DNS requests are cached for 1 minute.

never_direct allow ACL_NAME

To prevent Squid from taking requests directly from the Internet, use the option never_direct to force connection to another proxy. This must have previously been specified in cache_peer. If all is specified as the ACL_NAME, all requests are forwarded directly to the parent. This can be necessary, for example, if you are using a provider that dictates the use of its proxies or denies its firewall direct Internet access.

33.5.2 Options for Access Controls

Squid provides a detailed system for controlling the access to the proxy. These Access Control Lists (ACL) are lists with rules that are processed sequentially. ACLs must be defined before they can be used. Some default ACLs, such as all and localhost, already exist. However, the mere definition of an ACL does not mean that it is actually applied. This only happens when there is a corresponding http_access rule.

The syntax for the option acl is as follows:

acl ACL_NAME TYPE DATA

The placeholders within this syntax stand for the following:

  • The name ACL_NAME can be chosen arbitrarily.

  • For TYPE, select from a variety of different options which can be found in the ACCESS CONTROLS section in the /etc/squid/squid.conf file.

  • The specification for DATA depends on the individual ACL type and can also be read from a file. For example, via host names, IP addresses, or URLs.

To add rules in the YaST squid module, open the module and click the Access Control tab. Click Add under the ACL Groups list and enter the name of your rule, the type, and its parameters.

For more information on types of ACL rules, see the Squid documentation at http://www.squid-cache.org/Versions/v3/3.5/cfgman/acl.html.

Example 33.2: Defining ACL Rules
acl mysurfers srcdomain .example.com 1
acl teachers src 192.168.1.0/255.255.255.0 2
acl students src 192.168.7.0-192.168.9.0/255.255.255.0 3
acl lunch time MTWHF 12:00-15:00 4

1

This ACL defines mysurfers to be all users coming from within .example.com (as determined by a reverse lookup for the IP).

2

This ACL defines teachers to be the users of computers with IP addresses starting with 192.168.1..

3

This ACL defines students to be the users of the computer with IP addresses starting with 192.168.7., 192.168.8., or 192.168.9..

4

This ACL defines lunch as a time on the days Monday, Tuesday, ... Friday between noon and 3 p.m.

http_access allow ACL_NAME

http_access defines who is allowed to use the proxy and who can access what on the Internet. For this, ACLs must be defined. localhost and all have already been defined above for which you can deny or allow access via deny or allow. A list containing any number of http_access entries can be created, processed from top to bottom. Depending on which occurs first, access is allowed or denied to the respective URL. The last entry should always be http_access deny all. In the following example, localhost has free access to everything while all other hosts are denied access completely:

http_access allow localhost
http_access deny all

In another example using these rules, the group teachers always has access to the Internet. The group students only has access between Monday and Friday during lunch time:

http_access deny localhost
http_access allow teachers
http_access allow students lunch time
http_access deny all

For readability, within the configuration file /etc/squid/squid.conf, specify all http_access options as a block.

url_rewrite_program PATH

With this option, specify a URL rewriter. For example, this can be squidGuard (/usr/sbin/squidGuard) which allows blocking unwanted URLs. With it, Internet access can be individually controlled for various user groups using proxy authentication and the appropriate ACLs.

For more information on squidGuard, see Section 33.8, “squidGuard”.

auth_param basic program PATH

If users must be authenticated on the proxy, set a corresponding program, such as /usr/sbin/pam_auth. When accessing pam_auth for the first time, the user sees a login window in which they need to specify a user name and a password. In addition, you need an ACL, so only clients with a valid login can use the Internet:

acl password proxy_auth REQUIRED

http_access allow password
http_access deny all

In the acl proxy_auth option, using REQUIRED means that all valid user names are accepted. REQUIRED can also be replaced with a list of permitted user names.

ident_lookup_access allow ACL_NAME

With this option, have an ident request run to find each user's identity for all clients defined by an ACL of the type src. Alternatively, use this for all clients, apply the predefined ACL all as the ACL_NAME.

All clients covered by ident_lookup_access must run an ident daemon. On Linux, you can use pidentd (package pidentd ) as the ident daemon. For other operating systems, free software is usually available. To ensure that only clients with a successful ident lookup are permitted, define a corresponding ACL:

acl identhosts ident REQUIRED

http_access allow identhosts
http_access deny all

In the acl identhosts ident option, using REQUIRED means that all valid user names are accepted. REQUIRED can also be replaced with a list of permitted user names.

Using ident can slow down access time, because ident lookups are repeated for each request.

33.6 Configuring a Transparent Proxy

The usual way of working with proxy servers is as follows: the Web browser sends requests to a certain port of the proxy server and the proxy always provides these required objects, regardless of whether they are in its cache. However, in some cases the transparent proxy mode of Squid makes sense:

  • If, for security reasons, it is recommended that all clients use a proxy to surf the Internet.

  • If all clients must use a proxy, regardless of whether they are aware of it.

  • If the proxy in a network is moved, but the existing clients need to retain their old configuration.

A transparent proxy intercepts and answers the requests of the Web browser, so the Web browser receives the requested pages without knowing where they are coming from. As the name indicates, the entire process is transparent to the user.

Procedure 33.1: Squid as a Transparent Proxy (Command Line)
  1. In /etc/squid/squid.conf, on the line of the option http_port add the parameter transparent:

    http_port 3128 transparent
  2. Restart Squid:

    tux > sudo systemctl restart squid
  3. Set up SuSEFirewall2 to redirect HTTP traffic to the port given in http_proxy (in the example above, that was port 3128). To do so, edit the configuration file /etc/sysconfig/SuSEfirewall2.

    This example assumes that you are using the following devices:

    • Device pointing to the Internet: FW_DEV_EXT="eth1"

    • Device pointing to the network: FW_DEV_INT="eth0"

    Define ports and services (see /etc/services) on the firewall that are accessed from untrusted (external) networks such as the Internet. In this example, only Web services are offered to the outside:

    FW_SERVICES_EXT_TCP="www"

    Define ports or services (see /etc/services) on the firewall that are accessed from the secure (internal) network, both via TCP and UDP:

    FW_SERVICES_INT_TCP="domain www 3128"
    FW_SERVICES_INT_UDP="domain"

    This allows accessing Web services and Squid (whose default port is 3128). The service domain stands for DNS (domain name service). This service is commonly used. Otherwise, simply remove domain from the above entries and set the following option to no:

    FW_SERVICE_DNS="yes"

    The option FW_REDIRECT is very important, as it is used for the actual redirection of HTTP traffic to a specific port. The configuration file explains the syntax in a comment above the option:

    # Format:
    # list of <source network>[,<destination network>,<protocol>[,dport[:lport]]
    # Where protocol is either tcp or udp. dport is the original
    # destination port and lport the port on the local machine to
    # redirect the traffic to
    #
    # An exclamation mark in front of source or destination network
    # means everything EXCEPT the specified network

    That is:

    1. Specify the IP address and the netmask of the internal networks accessing the proxy firewall.

    2. Specify the IP address and the netmask to which these clients send their requests. In the case of Web browsers, specify the networks 0/0, a wild card that means to everywhere.

    3. Specify the original port to which these requests are sent.

    4. Specify the port to which all these requests are redirected. In the example below, only Web services (port 80) are redirected to the proxy port (port 3128). If there are more networks or services to add, separate them with a space in the respective entry.

      Because Squid supports protocols other than HTTP, you can also redirect requests from other ports to the proxy. For example, you can also redirect port 21 (FTP) and port 443 (HTTPS or SSL).

    Therefore, for a Squid configuration, you could use:

    FW_REDIRECT="192.168.0.0/16,0/0,tcp,80,3128"
  4. In the configuration file /etc/sysconfig/SuSEfirewall2, make sure that the entry START_FW is set to "yes".

  5. Restart SuSEFirewall2:

    tux > sudo systemctl restart SuSEfirewall2
  6. To verify that everything is working properly, check the Squid log files in /var/log/squid/access.log. To verify that all ports are correctly configured, perform a port scan on the machine from any computer outside your network. Only the Web services (port 80) should be open. To scan the ports with nmap, use:

    nmap -O IP_ADDRESS
Procedure 33.2: Squid as a Transparent Proxy (YaST)
  1. Start the YaST Squid module:

    1. In the Start-Up tab, enable Open Ports in Firewall. Click Firewall Details to select the interfaces on which to open the port. This option is available only if the Firewall is enabled.

    2. In the HTTP Ports tab, select the first line with the port 3128.

    3. Click the Edit button. A small window appear where you can edit the current HTTP port. Select Transparent.

    4. Finish with Ok.

  2. Configure the Firewall settings as described in Step 3 of Procedure 33.1, “Squid as a Transparent Proxy (Command Line)”.

33.7 Using the Squid Cache Manager CGI Interface (cachemgr.cgi)

The Squid cache manager CGI interface (cachemgr.cgi) is a CGI utility for displaying statistics about the memory usage of a running Squid process. It is also a convenient way to manage the cache and view statistics without logging the server.

Procedure 33.3: Setting up cachemgr.cgi
  1. Make sure the Apache Web server is running on your system. Configure Apache as described in Chapter 31, The Apache HTTP Server. In particular, see Section 31.5, “Enabling CGI Scripts”. To check whether Apache is already running, use:

    tux > sudo systemctl status apache2

    If inactive is shown, you can start Apache with the SUSE Linux Enterprise Server default settings:

    tux > sudo systemctl start apache2
  2. Now enable cachemgr.cgi in Apache. To do so, create a configuration file for a ScriptAlias.

    Create the file in the directory /etc/apache2/conf.d and name it cachemgr.conf. In it, add the following:

    ScriptAlias /squid/cgi-bin/ /usr/lib64/squid/
    
    <Directory "/usr/lib64/squid/">
    Options +ExecCGI
    AddHandler cgi-script .cgi
    Require host HOST_NAME
    </Directory>

    Replace HOST_NAME with the host name of the computer you want to access cachemgr.cgi from. This allows only your computer to access cachemgr.cgi. To allow access from anywhere, use Require all granted instead.

    • If Squid and your Apache Web server run on the same computer, there should be no changes that need to be made to /etc/squid/squid.conf. However, verify that /etc/squid/squid.conf contains the following lines:

        http_access allow manager localhost
        http_access deny manager

      These lines allow you to access the manager interface from your own computer (localhost) but not from elsewhere.

    • If Squid and your Apache Web server run on different computers, you need to add extra rules to allow access from the CGI script to Squid. Define an ACL for your server (replace WEB_SERVER_IP with the IP address of your Web server):

      acl webserver src WEB_SERVER_IP/255.255.255.255

      Make sure the following rules are in the configuration file. Compared to the default configuration, only the rule in the middle is new. However, the sequence is important.

      http_access allow manager localhost
      http_access allow manager webserver
      http_access deny manager
  3. (Optional) Optionally, you can configure one or more passwords for cachemgr.cgi. This also allows access to more actions such as closing the cache remotely or viewing more information about the cache. For this, configure the options cache_mgr and cachemgr_passwd with one or more password for the manager and a list of allowed actions.

    For example, to explicitly enable viewing the index page, the menu, 60-minute average of counters without authentication, to enable toggling offline mode using the password secretpassword, and to completely disable everything else, use the following configuration:

    cache_mgr user
    cachemgr_passwd none index menu 60min
    cachemgr_passwd secretpassword offline_toggle
    cachemgr_passwd disable all

    cache_mgr defines a user name. cache_mgr defines which actions are allowed using which password.

    The keywords none and disable are special: none removes the need for a password, disable disables functionality outright.

    The full list of actions can be best seen after logging in to cachemgr.cgi. To find out how the operation needs to be referenced in the configuration file, see the string after &operation= in the URL of the action page. all is a special keyword meaning all actions.

  4. Reload Squid and Apache after the configuration file changes:

    tux > sudo systemctl reload squid
  5. To view the statistics, go to the cachemgr.cgi page that you set up before. For example, it could be http://webserver.example.org/squid/cgi-bin/cachemgr.cgi.

    Choose the right server, and, if set, specify user name and password. Then click Continue and browse through the different statistics.

33.8 squidGuard

This section is not intended to explain an extensive configuration of squidGuard, only to introduce it and give some advice for using it. For more in-depth configuration issues, refer to the squidGuard Web site at http://www.squidguard.org.

squidGuard is a free (GPL), flexible, and fast filter, redirector, and access controller plug-in for Squid. It lets you define multiple access rules with different restrictions for different user groups on a Squid cache. squidGuard uses Squid's standard redirector interface. squidGuard can do the following:

  • Limit Web access for some users to a list of accepted or well-known Web servers or URLs.

  • Block access to some listed or blacklisted Web servers or URLs for some users.

  • Block access to URLs matching a list of regular expressions or words for some users.

  • Redirect blocked URLs to an intelligent CGI-based information page.

  • Redirect unregistered users to a registration form.

  • Redirect banners to an empty GIF.

  • Use different access rules based on time of day, day of the week, date, etc.

  • Use different rules for different user groups.

squidGuard and Squid cannot be used to:

  • Edit, filter, or censor text inside documents.

  • Edit, filter, or censor HTML-embedded scripts such as JavaScript.

Procedure 33.4: Setting Up squidGuard
  1. Before it can be used, install squidGuard .

  2. Provide a minimal configuration file as /etc/squidguard.conf. Find configuration examples in http://www.squidguard.org/Doc/examples.html. Experiment later with more complicated configuration settings.

  3. Next, create an access denied HTML page or CGI page that Squid can redirect to if the client requests a blacklisted Web site. Using Apache is strongly recommended.

  4. Now, configure Squid to use squidGuard. Use the following entry in the /etc/squid/squid.conf file:

    redirect_program /usr/bin/squidGuard
  5. Another option called redirect_children configures the number of redirect (in this case squidGuard) processes running on the machine. The more processes you set, the more RAM is required. Try low numbers first, for example, 4:

    redirect_children 4
  6. Last, have Squid load the new configuration by running systemctl reload squid. Now, test your settings with a browser.

33.9 Cache Report Generation with Calamaris

Calamaris is a Perl script used to generate reports of cache activity in ASCII or HTML format. It works with native Squid access log files. The Calamaris home page is located at http://cord.de/calamaris-english. This tool does not belong to the SUSE Linux Enterprise Server default installation scope—to use it, install the calamaris package.

Log in as root, then enter:

cat access1.log [access2.log access3.log] | calamaris OPTIONS > reportfile

When using more than one log file, make sure they are chronologically ordered, with older files listed first. This can be achieved by either listing the files one after the other as in the example above, or by using access{1..3}.log.

calamaris takes the following options:

-a

output all available reports

-w

output as HTML report

-l

include a message or logo in report header

More information about the various options can be found in the program's manual page with man calamaris.

A typical example is:

cat access.log.{10..1} access.log | calamaris -a -w \
> /usr/local/httpd/htdocs/Squid/squidreport.html

This puts the report in the directory of the Web server. Apache is required to view the reports.

33.10 For More Information

Visit the home page of Squid at http://www.squid-cache.org/. Here, find the Squid User Guide and a very extensive collection of FAQs on Squid.

In addition, mailing lists are available for Squid at http://www.squid-cache.org/Support/mailing-lists.html.

34 Web Based Enterprise Management Using SFCB

  • Filename: adm_wbem.xml
  • ID: cha.wbem

34.1 Introduction and Basic Concept

SUSE® Linux Enterprise Server (SLES) provides a collection of open standards based tools for the unified management of disparate computing systems and environments. Our enterprise solutions implement the standards proposed by the Distributed Management Task Force. The following paragraphs describe their basic components.

Distributed Management Task Force, Inc (DMTF) is the industry organization which leads the development of management standards for enterprise and Internet environments. Their goal is to unify management standards and initiatives, and to enable more integrated, cost effective and interoperable management solutions. DMTF standards provide common system management components for control and communication. Their solutions are independent of platforms and technologies. Web Based Enterprise Management and Common Information Model are one of their key technologies.

Web Based Enterprise Management (WBEM) is a set of management and Internet standard technologies. WBEM is developed to unify the management of enterprise computing environments. It provides the ability for the industry to deliver a well-integrated collection of management tools using Web technologies. WBEM consists of the following standards:

  • A data model: the Common Information Model (CIM) standard

  • An encoding specification: CIM-XML Encoding Specification

  • A transport mechanism: CIM operations over HTTP

Common Information Model is a conceptual information model that describes system management. It is not bound to a particular implementation and enables the interchange of management information between management systems, networks, services and applications. There are two parts to CIM — the CIM Specification and the CIM Schema.

  • The CIM Specification describes the language, naming and meta schema. The meta schema is a formal definition of the model. It defines the terms used to express the model and their usage and semantics. The elements of the meta schema are classes, properties, and methods. The meta schema also supports indications and associations as types of classes, and references as types of properties.

  • The CIM Schema provides the actual model descriptions. It supplies a set of classes with properties and associations that provide a well understood conceptual framework within which it is possible to organize the available information about the managed environment.

The Common Information Model Object Manager (CIMOM) is a CIM object manager or, more specifically, an application that manages objects according to the CIM standard. CIMOM manages communication between CIMOM providers and a CIM client, where the administrator manages the system.

CIMOM providers are software performing specific tasks within the CIMOM that are requested by client applications. Each provider instruments one or more aspects of the CIMOM's schema. These providers interact directly with the hardware.

Standards Based Linux Instrumentation for Manageability (SBLIM) is a collection of tools designed to support Web-Based Enterprise Management (WBEM). SUSE® Linux Enterprise Server uses the open source CIMOM (or CIM server) from the SBLIM project called Small Footprint CIM Broker .

Small Footprint CIM Broker is a CIM server intended for use in resource-limited or embedded environments. It is designed to be modular and lightweight at the same time. Its based on open standards and it supports CMPI providers, CIM-XML encoding, and Managed Object Format (MOF). It is highly configurable and performs stability even if the provider crashes. It is also easily accessible as it supports various transport protocols, such as HTTP, HTTPS, Unix domain sockets, Service Location Protocol (SLP), and Java Database Connectivity (JDBC).

34.2 Setting Up SFCB

To set up the Small Footprint CIM Broker (SFCB) environment, make sure the Web-Based Enterprise Management pattern in YaST is selected during SUSE Linux Enterprise Server installation. Alternatively, select it as a component to install on a server that is already running. Make sure the following packages are installed on your system:

cim-schema, Common Information Model (CIM) Schema

Contains the Common Information Model (CIM). CIM is a model for describing overall management information in a network or enterprise environments. CIM consists of a specification and a schema. The specification defines the details for integration with other management models. The schema provides the actual model descriptions.

cmpi-bindings-pywbem

Contains an adapter to write and run CMPI-type CIM providers in Python.

cmpi-pywbem-base

Contains base system CIM providers.

cmpi-pywbem-power-management

Contains power management providers based on DSP1027.

python-pywbem

Contains a Python module for making CIM operation calls through the WBEM protocol to query and update managed objects.

cmpi-provider-register, CIMOM neutral provider registration utility

Contains a utility allowing CMPI provider packages to register with whatever CIMOM happens to be present on the system.

sblim-sfcb, Small Footprint CIM Broker

Contains Small Footprint CIM Broker. It is a CIM server conforming to the CIM Operations over HTTP protocol. It is robust, with low resource consumption and, therefore, specifically suited for embedded and resource constrained environments. SFCB supports providers written against the Common Manageability Programming Interface (CMPI).

sblim-sfcc

Contains Small Footprint CIM Client library runtime libraries.

sblim-wbemcli

Contains WBEM command line interface. It is a stand-alone command line WBEM client especially suited for basic systems management tasks.

smis-providers

Contains providers to instrument the volumes and snapshots on the Linux file system. These are based on SNIA's SMI-S volume management profile and Copy Services profile respectively.

Package Selection for Web-Based Enterprise Management Pattern
Figure 34.1: Package Selection for Web-Based Enterprise Management Pattern

34.2.1 Installing Additional Providers

SUSE® Linux Enterprise Server software repository includes additional CIM providers that are not found in the Web-Based Enterprise Management installation pattern. You can easily get their list and installation status by searching the pattern sblim-cmpi- in the YaST software installation module. These providers cover various tasks of system management, such as DHCP, NFS, or kernel parameters setting. It is useful to install those providers which you are going to use with SFCB.

Package selection of additional CIM providers
Figure 34.2: Package selection of additional CIM providers

34.2.2 Starting, Stopping and Checking Status for SFCB

CIM server sfcbd daemon is installed together with Web-Based Enterprise Management software and is started by default at system start-up. The following table explains how to start, stop and check status for sfcbd.

Table 34.1: Commands for Managing sfcbd

Task

Linux Command

Start sfcbd

Enter systemctl start sfcb as root in the command line.

Stop sfcbd

Enter systemctl stop sfcb as root in the command line.

Check sfcbd status

Enter systemctl status sfcbas root in the command line.

34.2.3 Ensuring Secure Access

The default setup of SFCB is relatively secure. However, check that the access to SFCB components is as secure as required for your organization.

34.2.3.1 Certificates

Secure Socket Layers (SSL) transports require a certificate for secure communication to occur. When SFCB is installed, it has a self-signed certificate generated.

You can replace the path to the default certificate with a path to a commercial or self-signed one by changing the sslCertificateFilePath: PATH_FILENAME setting in /etc/sfcb/sfcb.cfg. The file must be in PEM format.

The default generated server certificate is in the following location:

/etc/sfcb/server.pem

Note
Note: Paths to SSL Certificates

The default generated certificate files servercert.pem and serverkey.pem are stored under /etc/ssl/servercerts directory. Files /etc/sfcb/client.pem, /etc/sfcb/file.pem and /etc/sfcb/server.pem are symbolic links to these files.

To generate a new certificate, enter the following command as root in the command line:

tux > sh /usr/share/sfcb/genSslCert.sh
Generating SSL certificates in .
Generating a 2048 bit RSA private key
...................................................................+++
.+++
writing new private key to '/var/tmp/sfcb.0Bjt69/key.pem'
-----

By default, the script generates certificates client.pem , file.pem and server.pem in the current working directory. If you want the script to generate the certificates in /etc/sfcb directory, you need to append it to the command. If these files already exist, a warning message is displayed and the old certificates are not overwritten.

tux > sh /usr/share/sfcb/genSslCert.sh /etc/sfcb
Generating SSL certificates in .
WARNING: server.pem SSL Certificate file already exists.
         old file will be kept intact.
WARNING: client.pem SSL Certificate trust store already exists.
         old file will be kept intact.

You must remove the old certificates from the file system and run the command again.

To change the way SFCB uses certificates, see Section 34.2.3.3, “Authentication”.

34.2.3.2 Ports

By default, SFCB is configured to accept all communications through the secure port 5989. The following paragraphs explain the communication port setup and recommended configuration.

Port 5989 (secure)

The secure port that SFCB communications use via HTTPS services. This is the default. With this setting, all communications between the CIMOM and client applications are encrypted when sent over the Internet between servers and workstations. Users must authenticate with the client application to reach SFCB server. We recommend that you keep this setting. For the SFCB CIMOM to communicate with the necessary applications, this port must be open on routers and firewalls if they are present between the client application and the nodes being monitored.

Port 5988 (insecure)

The insecure port that SFCB communications use via HTTP services. This setting is disabled by default. With this setting, all communications between the CIMOM and client applications are open for review when sent over the Internet between servers and workstations by anyone, without any authentication. We recommend that you use this setting only when attempting to debug a problem with the CIMOM. When the problem is resolved, disable the non-secure port option back. For the SFCB CIMOM to communicate with the necessary applications that require non-secure access, this port must be open in routers and firewalls between the client application and the nodes being monitored.

If you want to change the default port assignments, see Section 34.2.3.2, “Ports”.

34.2.3.3 Authentication

SFCB supports HTTP basic authentication and authentication based on client certificates (HTTP over SSL connections). Basic HTTP authentication is enabled by specifying doBasicAuth=true in the SFCB configuration file ( /etc/sfcb/sfcb.cfg by default). SUSE® Linux Enterprise Server installation of SFCB supports Pluggable Authentication Modules (PAM) approach; therefore the local root user can authenticate to the SFCB CIMOM with local root user credentials.

If the sslClientCertificate configuration property is set to accept or require, the SFCB HTTP adapter will request a certificate from clients when connecting via HTTP over SSL (HTTPS). If require is specified, the client must provide a valid certificate (according to the client trust store specified via sslClientTrustStore). If the client fails to do so, the connection will be rejected by the CIM server.

The setting sslClientCertificate=accept may not be obvious. It is very useful if both basic and client certificate authentication are allowed. If the client can provide a valid certificate, HTTPS connection will be established and the basic authentication procedure will not be executed. If this function cannot verify the certificate, the HTTP basic authentication will take place instead.

34.3 SFCB CIMOM Configuration

SFCB is a lightweight implementation of the CIM server, but it is also highly configurable. Several options can control its behavior. You can control the SFCB server in three ways:

  • by setting appropriate environment variables

  • by using command line options

  • by changing its configuration file

34.3.1 Environment Variables

Several environment variables directly affect the behavior of SFCB. You need to restart the SFCB daemon by systemctl restart sfcb for these changes to take effect.

PATH

Specifies the path to the sfcbd daemon and utilities.

LD_LIBRARY_PATH

Specifies the path to the sfcb runtime libraries. Alternatively, you can add this path to the system-wide dynamic loader configuration file /etc/ld.so.conf .

SFCB_PAUSE_PROVIDER

Specifies the provider name. The SFCB server pauses after the provider is loaded for the first time. You can then attach a runtime debugger to the provider's process for debugging purposes.

SFCB_PAUSE_CODEC

Specifies the name of the SFCB codec (currently supports only http. The SFCB server pauses after the codec is loaded for the first time. You can then attach a runtime debugger to the process.

SFCB_TRACE

Specifies the level of debug messages for SFCB. Valid values are 0 (no debug messages), or 1 (key debug messages) to 4 (all debug messages). Default is 1.

SFCB_TRACE_FILE

By default, SFCB outputs its debug messages to standard error output (STDERR). Setting this variable causes the debug messages to be written to a specified file instead.

SBLIM_TRACE

Specifies the level of debug messages for SBLIM providers. Valid values are 0 (no debug messages), or 1 (key debug messages) to 4 (all debug messages).

SBLIM_TRACE_FILE

By default, SBLIM provider outputs its trace messages to STDERR. Setting this variable causes the trace messages to be written to a specified file instead.

34.3.2 Command Line Options

sfcbd, the SFCB daemon, has several command line options that switch particular runtime features on or off. Enter these options when SFCB daemon starts.

-c, --config-file=FILE

When SFCB daemon starts, it reads its configuration from /etc/sfcb/sfcb.cfg by default. With this option, you can specify an alternative configuration file.

-d, --daemon

Forces sfcbd and its child processes to run in the background.

-s, --collect-stats

Turns on runtime statistics collecting. Various sfcbd runtime statistics will be written to the sfcbStat file in the current working directory. By default, no statistics are collected.

-l, --syslog-level=LOGLEVEL

Specifies the level of verbosity for the system logging facility. LOGLEVEL can be one of LOG_INFO, LOG_DEBUG, or LOG_ERR, which is the default.

-k, --color-trace=LOGLEVEL

Prints trace output in a different color per process for easier debugging.

-t, --trace-components=NUM

Activates component-level tracing messages, where NUM is an OR-ed bitmask integer that defines which component to trace. After you specify -t ?, it lists all the components and their associated integer bitmask:

tux > sfcbd -t ?
---   Traceable Components:     Int       Hex
---            providerMgr:          1  0x0000001
---            providerDrv:          2  0x0000002
---             cimxmlProc:          4  0x0000004
---             httpDaemon:          8  0x0000008
---                upCalls:         16  0x0000010
---               encCalls:         32  0x0000020
---        ProviderInstMgr:         64  0x0000040
---       providerAssocMgr:        128  0x0000080
---              providers:        256  0x0000100
---            indProvider:        512  0x0000200
---       internalProvider:       1024  0x0000400
---             objectImpl:       2048  0x0000800
---                  xmlIn:       4096  0x0001000
---                 xmlOut:       8192  0x0002000
---                sockets:      16384  0x0004000
---              memoryMgr:      32768  0x0008000
---               msgQueue:      65536  0x0010000
---             xmlParsing:     131072  0x0020000
---         responseTiming:     262144  0x0040000
---              dbpdaemon:     524288  0x0080000
---                    slp:    1048576  0x0100000

A useful value that reveals the internal functions of sfcbd but does not generate too many messages, is -t 2019.

34.3.3 SFCB Configuration File

SFCB reads its runtime configuration from configuration file /etc/sfcb/sfcb.cfg after starting up. This behavior can be overridden using -c option at start-up.

The configuration file contains option : VALUE pairs, one per line. When making changes to this file, you can use any text editor that saves the file in a format that is native to the environment you are using.

Any setting that has the options commented out with a number sign (#) uses the default setting.

The following list of options may not be complete. See the content of /etc/sfcb/sfcb.cfg and /usr/share/doc/packages/sblim-sfcb/README for their complete list.

34.3.3.1 httpPort

Purpose

Specifies the local port value that sfcbd should listen to receive HTTP (insecure) requests from CIM clients. Default is 5988 .

Syntax

httpPort: PORT_NUMBER

34.3.3.2 enableHttp

Purpose

Specifies whether SFCB should accept HTTP client connections. Default is false .

Syntax

enableHttp: OPTION

Option

Description

true

Enables HTTP connections.

false

Disables HTTP connections.

34.3.3.3 httpProcs

Purpose

Specifies the maximum number of simultaneous HTTP client connections before new incoming HTTP requests are blocked. Default is 8 .

Syntax

httpProcs: MAX_NUMBER_OF_CONNECTIONS

34.3.3.4 httpUserSFCB, httpUser

Purpose

These options control what user the HTTP server will run under. If httpUserSFCB is true, HTTP will run under the same user as the SFCB main process. If it is false the user name specified for httpUser will be used. This setting is used for both HTTP and HTTPS servers. httpUser must be specified if httpUserSFCB is set to false. the default is true.

Syntax

httpUserSFCB: true

34.3.3.5 httpLocalOnly

Purpose

Specifies whether to limit HTTP requests to localhost only. Default is false.

Syntax

httpLocalOnly: false

34.3.3.6 httpsPort

Purpose

Specifies the local port value where sfcbd listens for HTTPS requests from CIM clients. Default is 5989 .

Syntax

httpsPort: port_number

34.3.3.7 enableHttps

Purpose

Specifies if SFCB will accept HTTPS client connections. Default is true .

Syntax

enableHttps: option

Option

Description

true

Enables HTTPS connections.

false

Disables HTTPS connections.

34.3.3.8 httpsProcs

Purpose

Specifies the maximum number of simultaneous HTTPS client connections before new incoming HTTPS requests are blocked. Default is 8 .

Syntax

httpsProcs: MAX_NUMBER_OF_CONNECTIONS

34.3.3.9 enableInterOp

Purpose

Specifies if SFCB will provide the interop namespace for indication support. Default is true .

Syntax

enableInterOp: OPTION

Option

Description

true

Enables interop namespace.

false

Disables interop namespace.

34.3.3.10 provProcs

Purpose

Specifies the maximum number of simultaneous provider processes. After this point, if a new incoming request requires loading a new provider, then one of the existing providers will first be automatically unloaded. Default is 32 .

Syntax

provProcs: MAX_NUMBER_OF_PROCS

34.3.3.11 doBasicAuth

Purpose

Switches basic authentication on or off based on the client user identifier before it accepts the request. Default value is true which means that basic client authentication is performed.

Syntax

doBasicAuth: OPTION

Option

Description

true

Enables basic authentication.

false

Disables basic authentication.

34.3.3.12 basicAuthLib

Purpose

Specifies the local library name. The SFCB server loads the library to authenticate the client user identifier. Default is sfcBasicPAMAuthentication .

Syntax

provProcs: MAX_NUMBER_OF_PROCS

34.3.3.13 useChunking

Purpose

This option switches the use of HTTP/HTTPS chunking on or off. If switched on, the server will return large volumes of response data to the client in smaller chunks, rather than buffer the data and send it back all in one chunk. Default is true .

Syntax

useChunking: OPTION

Option

Description

true

Enables HTTP/HTTPS data chunking.

false

Disables HTTP/HTTPS data chunking.

34.3.3.14 keepaliveTimeout

Purpose

Specifies the maximum time in seconds that SFCB HTTP process waits between two requests on one connection before it terminates. Setting it to 0 disables HTTP keep-alive. Default is 0.

Syntax

keepaliveTimeout: SECS

34.3.3.15 keepaliveMaxRequest

Purpose

Specifies the maximum number of consecutive requests on one connection. Setting it to 0 disables HTTP keep-alive. Default value is 10 .

Syntax

keepaliveMaxRequest: NUMBER_OF_CONNECTIONS

34.3.3.16 registrationDir

Purpose

Specifies the registration directory, which contains the provider registration data, the staging area, and the static repository. Default is /var/lib/sfcb/registration .

Syntax

registrationDir: DIR

34.3.3.17 providerDirs

Purpose

Specifies a space-separated list of directories where SFCB is searching for provider libraries. Default is /usr/lib64 /usr/lib64 /usr/lib64/cmpi.

Syntax

providerDirs: DIR

34.3.3.18 providerSampleInterval

Purpose

Specifies the interval in seconds at which the provider manager is checking for idle providers. Default is 30.

Syntax

providerSampleInterval: SECS

34.3.3.19 providerTimeoutInterval

Purpose

Specifies the interval in seconds before an idle provider gets unloaded by the provider manager. Default is 60.

Syntax

providerTimeoutInterval: SECS

34.3.3.20 providerAutoGroup

Purpose

If the provider registration file does not specify any other group, and the option is set to true, all providers in the same shared library are executed in the same process.

Syntax

providerAutoGroup: OPTION

Option

Description

true

Enables grouping of providers.

false

Disables grouping of providers.

34.3.3.21 sslCertificateFilePath

Purpose

Specifies the name of the file that contains the server certificate. The file must be in PEM (Privacy Enhanced Mail, RFC 1421 and RFC 1424) format. This file is only required if enableHttps is set to true. Default is /etc/sfcb/server.pem.

Syntax

sslCertificateFilePath: PATH

34.3.3.22 sslKeyFilePath

Purpose

Specifies the name of the file that contains the private key for the server certificate. The file must be in PEM format and may not be protected by passphrase. This file is only required if enableHttps is set to true. Default is /etc/sfcb/file.pem.

Syntax

sslKeyFilePath: PATH

34.3.3.23 sslClientTrustStore

Purpose

Specifies the name of the file that contains either the CA or self-signed certificates of the clients. This file must be in PEM format and is only required if sslClientCertificate is set to accept or require. Default is /etc/sfcb/client.pem.

Syntax

sslClientTrustStore: PATH

34.3.3.24 sslClientCertificate

Purpose

Specifies the way SFCB handles client certificate based authentication. If set to ignore, it will not request a certificate from the client. If set to accept it will request a certificate from the client but will not fail if the client does not present one. If set to require, it will refuse the client connection if the client does not present a certificate. Default value is ignore.

Syntax

sslClientCertificate: OPTION

Option

Description

ignore

Disables requesting a client certificate.

accept

Disables requesting a client certificate.

Will not fail if no certificate is present.

require

Refuses the client connection without a valid certificate.

34.3.3.25 certificateAuthLib

Purpose

Specifies the name of the local library to request for the user authentication based on client certificate. This is only requested if sslClientCertificate is not set to ignore. Default value is sfcCertificateAuthentication.

Syntax

certificateAuthLib: FILE

34.3.3.26 traceLevel

Purpose

Specifies the trace level for SFCB. You can override it by setting environment variable SFCB_TRACE_LEVEL. Default value is 0.

Syntax

traceLevel: NUM_LEVEL

34.3.3.27 traceMask

Purpose

Specifies the trace mask for SFCB. you can override it by the command line option --trace-components. Default value is 0.

Syntax

traceMask: MASK

34.3.3.28 traceFile

Purpose

Specifies the trace file for SFCB. You can override it by setting environment variable SFCB_TRACE_FILE. Default value is stderr (standard error output).

Syntax

traceFile: OUTPUT

34.4 Advanced SFCB Tasks

This chapter covers more advanced topics related to SFCB usage. To understand them, you need to have basic knowledge of the Linux file system and experience with the Linux command line. This chapter includes the following tasks:

  • Installing CMPI providers

  • Testing SFCB

  • Using wbemcli CIM client

34.4.1 Installing CMPI Providers

To install a CMPI provider, you need to make sure that its shared library is copied into one of the directories specified by providerDirs configuration option, see Section 34.3.3.17, “providerDirs”. The provider must also be properly registered using sfcbstage and sfcbrepos commands.

The provider package is usually prepared for SFCB, so that its installation takes care of the proper registration. Most SBLIM providers are prepared for SFCB.

34.4.1.1 Class Repository

Class repository is a place where SFCB stores information about CIM classes. It usually consists of a directory tree with namespace components. Typical CIM namespaces are root/cimv2 or root/interop, which respectively translate to the class repository directory path on the file system

/var/lib/sfcb/registration/repository/root/cimv2

and

/var/lib/sfcb/registration/repository/root/interop

Each namespace directory contains the file classSchemas. The file has a compiled binary representation of all the CIM classes registered under that namespace. It also contains necessary information about their CIM superclasses.

In addition, each namespace directory may contain a file qualifiers which contains all qualifiers for the namespace. When sfcbd restarts, the class provider will scan the directory /var/lib/sfcb/registration/repository/ and all its subdirectories to determine the registered namespaces. Then classSchemas files are decoded and the class hierarchy for each namespace is built.

34.4.1.2 Adding New Classes

SFCB cannot make live CIM class manipulations. You need to add, change or remove classes offline and restart SFCB service with systemctl restart sfcb to register the changes.

To store providers class and registration information, SFCB uses a place called staging area. On SUSE® Linux Enterprise Server systems, it is the directory structure under /var/lib/sfcb/stage/.

To add a new provider, you need to:

  • Copy the provider class definition files to the ./mofs subdirectory of staging area directory (/var/lib/sfcb/stage/mofs).

  • Copy a registration file which contains the name of the class or classes and type of provider, and the name of the executable library file into the ./regs subdirectory.

There are two default mof (class definition) files in the staging directory: indication.mof and interop.mof. MOF files under the root stage directory /var/lib/sfcb/stage/mofs will be copied into each namespace after running sfcbrepos command. The interop.mof will only be compiled into the interop namespace.

The directory layout may look like the following example:

tux > ls /var/lib/sfcb/stage
default.reg  mofs  regs
tux > ls /var/lib/sfcb/stage/mofs
indication.mof  root
tux > ls /var/lib/sfcb/stage/mofs/root
cimv2  interop  suse  virt
tux > ls -1 /var/lib/sfcb/stage/mofs/root/cimv2 | less
Linux_ABIParameter.mof
Linux_BaseIndication.mof
Linux_Base.mof
Linux_DHCPElementConformsToProfile.mof
Linux_DHCPEntity.mof
[..]
OMC_StorageSettingWithHints.mof
OMC_StorageVolumeDevice.mof
OMC_StorageVolume.mof
OMC_StorageVolumeStorageSynchronized.mof
OMC_SystemStorageCapabilities.mof
tux > ls -1 /var/lib/sfcb/stage/mofs/root/interop
ComputerSystem.mof
ElementConformsToProfile.mof
HostSystem.mof
interop.mof
Linux_DHCPElementConformsToProfile.mof
[..]
OMC_SMIElementSoftwareIdentity.mof
OMC_SMISubProfileRequiresProfile.mof
OMC_SMIVolumeManagementSoftware.mof
ReferencedProfile.mof
RegisteredProfile.mof
tux > ls -1 /var/lib/sfcb/stage/regs
AllocationCapabilities.reg
Linux_ABIParameter.reg
Linux_BaseIndication.reg
Linux_DHCPGlobal.reg
Linux_DHCPRegisteredProfile.reg
[..]
OMC_Base.sfcb.reg
OMC_CopyServices.sfcb.reg
OMC_PowerManagement.sfcb.reg
OMC_Server.sfcb.reg
RegisteredProfile.reg
tux > cat /var/lib/sfcb/stage/regs/Linux_DHCPRegisteredProfile.reg
[Linux_DHCPRegisteredProfile]
   provider: Linux_DHCPRegisteredProfileProvider
   location: cmpiLinux_DHCPRegisteredProfile
   type: instance
   namespace: root/interop
#
[Linux_DHCPElementConformsToProfile]
   provider: Linux_DHCPElementConformsToProfileProvider
   location: cmpiLinux_DHCPElementConformsToProfile
   type: instance association
   namespace: root/cimv2
#
[Linux_DHCPElementConformsToProfile]
   provider: Linux_DHCPElementConformsToProfileProvider
   location: cmpiLinux_DHCPElementConformsToProfile
   type: instance association
   namespace: root/interop

SFCB uses a custom provider registration file for each provider.

Note
Note: SBLIM Providers Registration Files

All SBLIM providers on the SBLIM Web site already include a registration file that is used to generate the .reg file for SFCB.

The format of SFCB registration file is:

[<class-name>]
   provider: <provide-name>
   location: <library-name>
   type: [instance] [association] [method] [indication]
   group: <group-name>
   unload: never
   namespace: <namespace-for-class> ...

where:

<class-name>

The CIM class name (required)

<provider-name>

The CMPI provider name (required)

<location-name>

The name of the provider library (required)

type

The type of the provider (required). This can be any combination of: instance, association, method or indication.

<group-name>

Multiple providers can be grouped together and run under a single process to further minimize runtime resources. All providers registered under the same <group-name> will be executed under the same process. By default each provider will be run as a separate process.

unload

Specifies the unload policy for the provider. Currently the only supported option is never, which specifies that the provider will not be monitored for idle times and will never be unloaded. By default each provider will be unloaded when its idle times exceed the value specified in the configuration file.

namespace

List of namespaces for which this provider can be executed. This is required, although for most providers this will be root/cimv2.

Once all the class definitions and provider registration files are stored in the staging area, you need to rebuild the SFCB class repository with the command sfcbrepos -f.

You can add, change or remove classes this way. After rebuilding the class repository, restart SFCB with command systemctl restart sfcb.

Alternatively, the SFCB package contains a utility that will copy provider class mof files and registration files to the correct locations in the staging area.

sfcbstage -r [provider.reg] [class1.mof] [class2.mof] ...

After running this command you still need to rebuild the class repository and restart SFCB service.

34.4.2 Testing SFCB

The SFCB package includes two testing scripts: wbemcat and xmltest.

wbemcat sends raw CIM-XML data via HTTP protocol to the specified SFCB host (localhost by default) listening on port 5988. Then it displays the returned results. The following file contains the CIM-XML representation of a standard EnumerateClasses request:

<?xml version="1.0" encoding="utf-8"?>
<CIM CIMVERSION="2.0" DTDVERSION="2.0">
  <MESSAGE ID="4711" PROTOCOLVERSION="1.0">
    <SIMPLEREQ>
      <IMETHODCALL NAME="EnumerateClasses">
        <LOCALNAMESPACEPATH>
          <NAMESPACE NAME="root"/>
          <NAMESPACE NAME="cimv2"/>
        </LOCALNAMESPACEPATH>
        <IPARAMVALUE NAME="ClassName">
          <CLASSNAME NAME=""/>
        </IPARAMVALUE>
        <IPARAMVALUE NAME="DeepInheritance">
          <VALUE>TRUE</VALUE>
        </IPARAMVALUE>
        <IPARAMVALUE NAME="LocalOnly">
          <VALUE>FALSE</VALUE>
        </IPARAMVALUE>
        <IPARAMVALUE NAME="IncludeQualifiers">
          <VALUE>FALSE</VALUE>
        </IPARAMVALUE>
        <IPARAMVALUE NAME="IncludeClassOrigin">
          <VALUE>TRUE</VALUE>
        </IPARAMVALUE>
      </IMETHODCALL>
    </SIMPLEREQ>
  </MESSAGE>
</CIM>

Sending this request to SFCB CIMOM returns a list of all supported classes for which there is a registered provider. Suppose you save the file as cim_xml_test.xml.

tux > wbemcat cim_xml_test.xml | less
HTTP/1.1 200 OK
Content-Type: application/xml; charset="utf-8"
Content-Length: 337565
Cache-Control: no-cache
CIMOperation: MethodResponse

<?xml version="1.0" encoding="utf-8" ?>
<CIM CIMVERSION="2.0" DTDVERSION="2.0">
<MESSAGE ID="4711" PROTOCOLVERSION="1.0">
<SIMPLERSP>
<IMETHODRESPONSE NAME="EnumerateClasses">
[..]
<CLASS NAME="Linux_DHCPParamsForEntity" SUPERCLASS="CIM_Component">
<PROPERTY.REFERENCE NAME="GroupComponent" REFERENCECLASS="Linux_DHCPEntity">
</PROPERTY.REFERENCE>
<PROPERTY.REFERENCE NAME="PartComponent" REFERENCECLASS="Linux_DHCPParams">
</PROPERTY.REFERENCE>
</CLASS>
</IRETURNVALUE>
</IMETHODRESPONSE>
</SIMPLERSP>
</MESSAGE>
</CIM>

The classes listed will vary depending on what providers are installed on your system.

The second script xmltest is also used to send a raw CIM-XML test file to the SFCB CIMOM. It then compares the returned results against a previously saved OK result file. If there does not yet exist a corresponding OK file, it will be created for later use:

tux > xmltest cim_xml_test.xml
Running test cim_xml_test.xml ... OK
        Saving response as cim_xml_test.OK
root # xmltest cim_xml_test.xml
Running test cim_xml_test.xml ... Passed

34.4.3 Command Line CIM Client: wbemcli

In addition to wbemcat and xmltest, the SBLIM project includes a more advanced command line CIM client wbemcli. The client is used to send CIM requests to SFCB server and display returned results. It is independent of CIMOM library and can be used with all WBEM compliant implementations.

For example, if you need to list all the classes implemented by SBLIM providers registered to your SFCB, send the EnumerateClasses (ec) request to SFCB:

tux > wbemcli -dx ec http://localhost/root/cimv2
To server: <?xml version="1.0" encoding="utf-8" ?>
<CIM CIMVERSION="2.0" DTDVERSION="2.0">
<MESSAGE ID="4711" PROTOCOLVERSION="1.0"><SIMPLEREQ><IMETHODCALL \
    NAME="EnumerateClasses"><LOCALNAMESPACEPATH><NAMESPACE NAME="root"> \
    </NAMESPACE><NAMESPACE NAME="cimv2"></NAMESPACE> \
    </LOCALNAMESPACEPATH>
<IPARAMVALUE NAME="DeepInheritance"><VALUE>TRUE</VALUE> \
    </IPARAMVALUE>
<IPARAMVALUE NAME="LocalOnly"><VALUE>FALSE</VALUE></IPARAMVALUE>
<IPARAMVALUE NAME="IncludeQualifiers"><VALUE>FALSE</VALUE> \
    </IPARAMVALUE>
<IPARAMVALUE NAME="IncludeClassOrigin"><VALUE>TRUE</VALUE> \
    </IPARAMVALUE>
</IMETHODCALL></SIMPLEREQ>
</MESSAGE></CIM>
From server: Content-Type: application/xml; charset="utf-8"
From server: Content-Length: 337565
From server: Cache-Control: no-cache
From server: CIMOperation: MethodResponse
From server: <?xml version="1.0" encoding="utf-8" ?>
<CIM CIMVERSION="2.0" DTDVERSION="2.0">
<MESSAGE ID="4711" PROTOCOLVERSION="1.0">
<SIMPLERSP>
<IMETHODRESPONSE NAME="EnumerateClasses">
<IRETURNVALUE>
<CLASS NAME="CIM_ResourcePool" SUPERCLASS="CIM_LogicalElement">
<PROPERTY NAME="Generation" TYPE="uint64">
</PROPERTY>
<PROPERTY NAME="ElementName" TYPE="string">
</PROPERTY>
<PROPERTY NAME="Description" TYPE="string">
</PROPERTY>
<PROPERTY NAME="Caption" TYPE="string">
</PROPERTY>
<PROPERTY NAME="InstallDate" TYPE="datetime">
</PROPERTY>
[..]
<CLASS NAME="Linux_ReiserFileSystem" SUPERCLASS="CIM_UnixLocalFileSystem">
<PROPERTY NAME="FSReservedCapacity" TYPE="uint64">
</PROPERTY>
<PROPERTY NAME="TotalInodes" TYPE="uint64">
</PROPERTY>
<PROPERTY NAME="FreeInodes" TYPE="uint64">
</PROPERTY>
<PROPERTY NAME="ResizeIncrement" TYPE="uint64">
<VALUE>0</VALUE>
</PROPERTY>
<PROPERTY NAME="IsFixedSize" TYPE="uint16">
<VALUE>0</VALUE>
</PROPERTY>
[..]

The -dx option shows you the actual XML sent to SFCB by wbemcli and the actual XML received. In the above example, the first of many returned classes was CIM_ResourcePool followed by Linux_ReiserFileSystem. Similar entries will appear for all of the other registered classes.

If you omit the -dx option, wbemcli will display only a compact representation of the returned data:

tux > wbemcli ec http://localhost/root/cimv2
localhost:5988/root/cimv2:CIM_ResourcePool Generation=,ElementName=, \
    Description=,Caption=,InstallDate=,Name=,OperationalStatus=, \
    StatusDescriptions=,Status=,HealthState=,PrimaryStatus=, \
    DetailedStatus=,OperatingStatus=,CommunicationStatus=,InstanceID=, \
    PoolID=,Primordial=,Capacity=,Reserved=,ResourceType=, \
    OtherResourceType=,ResourceSubType=, \AllocationUnits=
localhost:5988/root/cimv2:Linux_ReiserFileSystem FSReservedCapacity=, \
    TotalInodes=,FreeInodes=,ResizeIncrement=,IsFixedSize=,NumberOfFiles=, \
    OtherPersistenceType=,PersistenceType=,FileSystemType=,ClusterSize=, \
    MaxFileNameLength=,CodeSet=,CasePreserved=,CaseSensitive=, \
    CompressionMethod=,EncryptionMethod=,ReadOnly=,AvailableSpace=, \
    FileSystemSize=,BlockSize=,Root=,Name=,CreationClassName=,CSName=, \
    CSCreationClassName=,Generation=,ElementName=,Description=,Caption=, \
    InstanceID=,InstallDate=,OperationalStatus=,StatusDescriptions=, \
    Status=,HealthState=,PrimaryStatus=,DetailedStatus=,OperatingStatus= \
    ,CommunicationStatus=,EnabledState=,OtherEnabledState=,RequestedState= \
    ,EnabledDefault=,TimeOfLastStateChange=,AvailableRequestedStates=, \
    TransitioningToState=,PercentageSpaceUse=
    [..]

34.5 For More Information

For more details about WBEM and SFCB, see the following sources:
http://www.dmtf.org

Distributed Management Task Force Web site

http://www.dmtf.org/standards/wbem/

Web-Based Enterprise Management (WBEM) Web site

http://www.dmtf.org/standards/cim/

Common Information Model (CIM) Web site

http://sblim.wiki.sourceforge.net/

Standards Based Linux Instrumentation (SBLIM) Web site

http://sblim.sourceforge.net/wiki/index.php/Sfcb

Small Footprint CIM Broker (SFCB) Web site

http://sblim.sourceforge.net/wiki/index.php/Providers

SBLIM providers packages

Part V Mobile Computers

35 Mobile Computing with Linux

Mobile computing is mostly associated with laptops, PDAs and cellular phones (and the data exchange between them). Mobile hardware components, such as external hard disks, flash disks, or digital cameras, can be connected to laptops or desktop systems. A number of software components are involved in mobile computing scenarios and some applications are tailor-made for mobile use.

36 Using NetworkManager

NetworkManager is the ideal solution for laptops and other portable computers. It supports state-of-the-art encryption types and standards for network connections, including connections to 802.1X protected networks. 802.1X is the “IEEE Standard for Local and Metropolitan Area Networks—Port-Based Net…

37 Power Management

The features and hardware described in this chapter do not exist on IBM z Systems, making this chapter irrelevant for these platforms.

35 Mobile Computing with Linux

  • Filename: mobile.xml
  • ID: cha.mobile
Abstract

Mobile computing is mostly associated with laptops, PDAs and cellular phones (and the data exchange between them). Mobile hardware components, such as external hard disks, flash disks, or digital cameras, can be connected to laptops or desktop systems. A number of software components are involved in mobile computing scenarios and some applications are tailor-made for mobile use.

35.1 Laptops

The hardware of laptops differs from that of a normal desktop system. This is because criteria like exchangeability, space requirements and power consumption must be taken into account. The manufacturers of mobile hardware have developed standard interfaces like PCMCIA (Personal Computer Memory Card International Association), Mini PCI and Mini PCIe that can be used to extend the hardware of laptops. The standards cover memory cards, network interface cards, and external hard disks.

35.1.1 Power Conservation

The inclusion of energy-optimized system components during laptop manufacturing contributes to their suitability for use without access to the electrical power grid. Their contribution to conservation of power is at least as important as that of the operating system. SUSE® Linux Enterprise Server supports various methods that control the power consumption of a laptop and have varying effects on the operating time under battery power. The following list is in descending order of contribution to power conservation:

  • Throttling the CPU speed.

  • Switching off the display illumination during pauses.

  • Manually adjusting the display illumination.

  • Disconnecting unused, hotplug-enabled accessories (USB CD-ROM, external mouse, unused PCMCIA cards, Wi-Fi, etc.).

  • Spinning down the hard disk when idling.

Detailed background information about power management in SUSE Linux Enterprise Server is provided in Chapter 37, Power Management.

35.1.2 Integration in Changing Operating Environments

Your system needs to adapt to changing operating environments when used for mobile computing. Many services depend on the environment and the underlying clients must be reconfigured. SUSE Linux Enterprise Server handles this task for you.

Integrating a Mobile Computer in an Existing Environment
Figure 35.1: Integrating a Mobile Computer in an Existing Environment

The services affected in the case of a laptop commuting back and forth between a small home network and an office network are:

Network

This includes IP address assignment, name resolution, Internet connectivity and connectivity to other networks.

Printing

A current database of available printers and an available print server must be present, depending on the network.

E-Mail and Proxies

As with printing, the list of the corresponding servers must be current.

X (Graphical Environment)

If your laptop is temporarily connected to a projector or an external monitor, different display configurations must be available.

SUSE Linux Enterprise Server offers several ways of integrating laptops into existing operating environments:

NetworkManager

NetworkManager is especially tailored for mobile networking on laptops. It provides a means to easily and automatically switch between network environments or different types of networks such as mobile broadband (such as GPRS, EDGE, or 3G), wireless LAN, and Ethernet. NetworkManager supports WEP and WPA-PSK encryption in wireless LANs. It also supports dial-up connections. The GNOME desktop includes a front-end for NetworkManager. For more information, see Section 36.3, “Configuring Network Connections”.

Table 35.1: Use Cases for NetworkManager

My computer…

Use NetworkManager

is a laptop

Yes

is sometimes attached to different networks

Yes

provides network services (such as DNS or DHCP)

No

only uses a static IP address

No

Use the YaST tools to configure networking whenever NetworkManager should not handle network configuration.

Tip
Tip: DNS Configuration and Various Types of Network Connections

If you travel frequently with your laptop and change different types of network connections, NetworkManager works fine when all DNS addresses are assigned correctly assigned with DHCP. If some connections use static DNS address(es), add it to the NETCONFIG_DNS_STATIC_SERVERS option in /etc/sysconfig/network/config.

SLP

The service location protocol (SLP) simplifies the connection of a laptop to an existing network. Without SLP, the administrator of a laptop usually requires detailed knowledge of the services available in a network. SLP broadcasts the availability of a certain type of service to all clients in a local network. Applications that support SLP can process the information dispatched by SLP and be configured automatically. SLP can also be used to install a system, minimizing the effort of searching for a suitable installation source. Find detailed information about SLP in Chapter 30, SLP.

35.1.3 Software Options

There are various task areas in mobile use that are covered by dedicated software: system monitoring (especially the battery charge), data synchronization, and wireless communication with peripherals and the Internet. The following sections cover the most important applications that SUSE Linux Enterprise Server provides for each task.

35.1.3.1 System Monitoring

Two system monitoring tools are provided by SUSE Linux Enterprise Server:

Power Management

Power Management is an application that lets you adjust the energy saving related behavior of the GNOME desktop. You can typically access it via Computer › Control Center › System › Power Management.

System Monitor

The System Monitor gathers measurable system parameters into one monitoring environment. It presents the output information in three tabs by default. Processes gives detailed information about currently running processes, such as CPU load, memory usage, or process ID number and priority. The presentation and filtering of the collected data can be customized—to add a new type of process information, left-click the process table header and choose which column to hide or add to the view. It is also possible to monitor different system parameters in various data pages or collect the data of various machines in parallel over the network. The Resources tab shows graphs of CPU, memory and network history and the File System tab lists all partitions and their usage.

35.1.3.2 Synchronizing Data

When switching between working on a mobile machine disconnected from the network and working at a networked workstation in an office, it is necessary to keep processed data synchronized across all instances. This could include e-mail folders, directories and individual files that need to be present for work on the road and at the office. The solution in both cases is as follows:

Synchronizing E-Mail

Use an IMAP account for storing your e-mails in the office network. Then access the e-mails from the workstation using any disconnected IMAP-enabled e-mail client, like Mozilla Thunderbird or Evolution as described in GNOME User Guide. The e-mail client must be configured so that the same folder is always accessed for Sent messages. This ensures that all messages are available along with their status information after the synchronization process has completed. Use an SMTP server implemented in the mail client for sending messages instead of the system-wide MTA postfix or sendmail to receive reliable feedback about unsent mail.

Synchronizing Files and Directories

There are several utilities suitable for synchronizing data between a laptop and a workstation. One of the most widely used is a command-line tool called rsync. For more information, see its manual page (man 1 rsync).

35.1.3.3 Wireless Communication: Wi-Fi

With the largest range of these wireless technologies, Wi-Fi is the only one suitable for the operation of large and sometimes even spatially separate networks. Single machines can connect with each other to form an independent wireless network or access the Internet. Devices called access points act as base stations for Wi-Fi-enabled devices and act as intermediaries for access to the Internet. A mobile user can switch among access points depending on location and which access point is offering the best connection. Like in cellular telephony, a large network is available to Wi-Fi users without binding them to a specific location for accessing it.

Wi-Fi cards communicate using the 802.11 standard, prepared by the IEEE organization. Originally, this standard provided for a maximum transmission rate of 2 Mbit/s. Meanwhile, several supplements have been added to increase the data rate. These supplements define details such as the modulation, transmission output, and transmission rates (see Table 35.2, “Overview of Various Wi-Fi Standards”). Additionally, many companies implement hardware with proprietary or draft features.

Table 35.2: Overview of Various Wi-Fi Standards

Name (802.11)

Frequency (GHz)

Maximum Transmission Rate (Mbit/s)

Note

a

5

54

Less interference-prone

b

2.4

11

Less common

g

2.4

54

Widespread, backward-compatible with 11b

n

2.4 and/or 5

300

Common

ac

5

up to ~865

Expected to be common in 2015

ad

60

up to appr. 7000

Released 2012, currently less common; not supported in SUSE Linux Enterprise Server

802.11 Legacy cards are not supported by SUSE® Linux Enterprise Server. Most cards using 802.11 a/b/g/n are supported. New cards usually comply with the 802.11n standard, but cards using 802.11g are still available.

35.1.3.3.1 Operating Modes

In wireless networking, various techniques and configurations are used to ensure fast, high-quality, and secure connections. Usually your Wi-Fi card operates in managed mode. However, different operating types need different setups. Wireless networks can be classified into four network modes:

Managed Mode (Infrastructure Mode), via Access Point (default mode)

Managed networks have a managing element: the access point. In this mode (also called infrastructure or default mode), all connections of the Wi-Fi stations in the network run through the access point, which may also serve as a connection to an Ethernet. To make sure only authorized stations can connect, various authentication mechanisms (WPA, etc.) are used. This is also the main mode that consumes the least amount of energy.

Ad-hoc Mode (Peer-to-Peer Network)

Ad-hoc networks do not have an access point. The stations communicate directly with each other, therefore an ad-hoc network is usually slower than a managed network. However, the transmission range and number of participating stations are greatly limited in ad-hoc networks. They also do not support WPA authentication. Additionally, not all cards support ad-hoc mode reliably.

Master Mode

In master mode, your Wi-Fi card is used as the access point, assuming your card supports this mode. Find out the details of your Wi-Fi card at http://linux-wless.passys.nl.

Mesh Mode

Wireless mesh networks are organized in a mesh topology. A wireless mesh network's connection is spread among all wireless mesh nodes. Each node belonging to this network is connected to other nodes to share the connection, possibly over a large area. (Not supported in SLE12).

35.1.3.3.2 Authentication

Because a wireless network is much easier to intercept and compromise than a wired network, the various standards include authentication and encryption methods.

Old Wi-Fi cards support only WEP (Wired Equivalent Privacy). However, because WEP has proven to be insecure, the Wi-Fi industry has defined an extension called WPA, which is supposed to eliminate the weaknesses of WEP. WPA, sometimes synonymous with WPA2, should be the default authentication method.

Usually the user cannot choose the authentication method. For example, when a card operates in managed mode the authentication is set by the access point. NetworkManager shows the authentication method.

35.1.3.3.3 Encryption

There are various encryption methods to ensure that no unauthorized person can read the data packets that are exchanged in a wireless network or gain access to the network:

WEP (defined in IEEE 802.11)

This standard uses the RC4 encryption algorithm, originally with a key length of 40 bits, later also with 104 bits. Often, the length is declared as 64 bits or 128 bits, depending on whether the 24 bits of the initialization vector are included. However, this standard has some weaknesses. Attacks against the keys generated by this system may be successful. Nevertheless, it is better to use WEP than not to encrypt the network.

Some vendors have implemented the non-standard Dynamic WEP. It works exactly as WEP and shares the same weaknesses, except that the key is periodically changed by a key management service.

TKIP (defined in WPA/IEEE 802.11i)

This key management protocol defined in the WPA standard uses the same encryption algorithm as WEP, but eliminates its weakness. Because a new key is generated for every data packet, attacks against these keys are fruitless. TKIP is used together with WPA-PSK.

CCMP (defined in IEEE 802.11i)

CCMP describes the key management. Usually, it is used in connection with WPA-EAP, but it can also be used with WPA-PSK. The encryption takes place according to AES and is stronger than the RC4 encryption of the WEP standard.

35.1.3.4 Wireless Communication: Bluetooth

Bluetooth has the broadest application spectrum of all wireless technologies. It can be used for communication between computers (laptops) and PDAs or cellular phones, as can IrDA. It can also be used to connect various computers within range. Bluetooth is also used to connect wireless system components, like a keyboard or a mouse. The range of this technology is, however, not sufficient to connect remote systems to a network. Wi-Fi is the technology of choice for communicating through physical obstacles like walls.

35.1.3.5 Wireless Communication: IrDA

IrDA is the wireless technology with the shortest range. Both communication parties must be within viewing distance of each other. Obstacles like walls cannot be overcome. One possible application of IrDA is the transmission of a file from a laptop to a cellular phone. The short path from the laptop to the cellular phone is then covered using IrDA. Long-range transmission of the file to the recipient is handled by the mobile network. Another application of IrDA is the wireless transmission of printing jobs in the office.

35.1.4 Data Security

Ideally, you protect data on your laptop against unauthorized access in multiple ways. Possible security measures can be taken in the following areas:

Protection against Theft

Always physically secure your system against theft whenever possible. Various securing tools (like chains) are available in retail stores.

Strong Authentication

Use biometric authentication in addition to standard authentication via login and password. SUSE Linux Enterprise Server supports fingerprint authentication.

Securing Data on the System

Important data should not only be encrypted during transmission, but also on the hard disk. This ensures its safety in case of theft. The creation of an encrypted partition with SUSE Linux Enterprise Server is described in Chapter 11, Encrypting Partitions and Files. Another possibility is to create encrypted home directories when adding the user with YaST.

Important
Important: Data Security and Suspend to Disk

Encrypted partitions are not unmounted during a suspend to disk event. Thus, all data on these partitions is available to any party who manages to steal the hardware and issue a resume of the hard disk.

Network Security

Any transfer of data should be secured, no matter how the transfer is done. Find general security issues regarding Linux and networks in Chapter 1, Security and Confidentiality.

35.2 Mobile Hardware

SUSE Linux Enterprise Server supports the automatic detection of mobile storage devices over FireWire (IEEE 1394) or USB. The term mobile storage device applies to any kind of FireWire or USB hard disk, flash disk, or digital camera. These devices are automatically detected and configured when they are connected with the system over the corresponding interface. The file manager of GNOME offers flexible handling of mobile hardware items. To unmount any of these media safely, use the Unmount Volume (GNOME) feature of the file manager. For more details refer to GNOME User Guide.

External Hard Disks (USB and FireWire)

When an external hard disk is correctly recognized by the system, its icon appears in the file manager. Clicking the icon displays the contents of the drive. It is possible to create directories and files here and edit or delete them. To rename a hard disk, select the corresponding menu item from the right-click contextual menu. This name change is limited to display in the file manager. The descriptor by which the device is mounted in /media remains unaffected.

USB Flash Disks

These devices are handled by the system like external hard disks. It is similarly possible to rename the entries in the file manager.

35.3 Cellular Phones and PDAs

A desktop system or a laptop can communicate with a cellular phone via Bluetooth or IrDA. Some models support both protocols and some only one of the two. The usage areas for the two protocols and the corresponding extended documentation has already been mentioned in Section 35.1.3.3, “Wireless Communication: Wi-Fi”. The configuration of these protocols on the cellular phones themselves is described in their manuals.

35.4 For More Information

The central point of reference for all questions regarding mobile devices and Linux is http://tuxmobil.org/. Various sections of that Web site deal with the hardware and software aspects of laptops, PDAs, cellular phones and other mobile hardware.

A similar approach to that of http://tuxmobil.org/ is made by http://www.linux-on-laptops.com/. Information about laptops and handhelds can be found here.

SUSE maintains a mailing list in German dedicated to the subject of laptops. See http://lists.opensuse.org/opensuse-mobile-de/. On this list, users and developers discuss all aspects of mobile computing with SUSE Linux Enterprise Server. Postings in English are answered, but the majority of the archived information is only available in German. Use http://lists.opensuse.org/opensuse-mobile/ for English postings.

36 Using NetworkManager

  • Filename: nm.xml
  • ID: cha.nm

NetworkManager is the ideal solution for laptops and other portable computers. It supports state-of-the-art encryption types and standards for network connections, including connections to 802.1X protected networks. 802.1X is the IEEE Standard for Local and Metropolitan Area Networks—Port-Based Network Access Control. With NetworkManager, you need not worry about configuring network interfaces and switching between wired or wireless networks when you are moving. NetworkManager can automatically connect to known wireless networks or manage several network connections in parallel—the fastest connection is then used as default. Furthermore, you can manually switch between available networks and manage your network connection using an applet in the system tray.

Instead of only one connection being active, multiple connections may be active at once. This enables you to unplug your laptop from an Ethernet and remain connected via a wireless connection.

36.1 Use Cases for NetworkManager

NetworkManager provides a sophisticated and intuitive user interface, which enables users to easily switch their network environment. However, NetworkManager is not a suitable solution in the following cases:

  • Your computer provides network services for other computers in your network, for example, it is a DHCP or DNS server.

  • Your computer is a Xen server or your system is a virtual system inside Xen.

36.2 Enabling or Disabling NetworkManager

On laptop computers, NetworkManager is enabled by default. However, it can be at any time enabled or disabled in the YaST Network Settings module.

  1. Run YaST and go to System › Network Settings.

  2. The Network Settings dialog opens. Go to the Global Options tab.

  3. To configure and manage your network connections with NetworkManager:

    1. In the Network Setup Method field, select User Controlled with NetworkManager.

    2. Click OK and close YaST.

    3. Configure your network connections with NetworkManager as described in Section 36.3, “Configuring Network Connections”.

  4. To deactivate NetworkManager and control the network with your own configuration

    1. In the Network Setup Method field, choose Controlled by wicked.

    2. Click OK.

    3. Set up your network card with YaST using automatic configuration via DHCP or a static IP address.

      Find a detailed description of the network configuration with YaST in Section 16.4, “Configuring a Network Connection with YaST”.

36.3 Configuring Network Connections

After having enabled NetworkManager in YaST, configure your network connections with the NetworkManager front-end available in GNOME. It shows tabs for all types of network connections, such as wired, wireless, mobile broadband, DSL, and VPN connections.

To open the network configuration dialog in GNOME, open the settings menu via the status menu and click the Network entry.

Note
Note: Availability of Options

Depending on your system setup, you may not be allowed to configure connections. In a secured environment, some options may be locked or require root permission. Ask your system administrator for details.

GNOME Network Connections Dialog
Figure 36.1: GNOME Network Connections Dialog
Procedure 36.1: Adding and Editing Connections
  1. Open the NetworkManager configuration dialog.

  2. To add a Connection:

    1. Click the + icon in the lower left corner.

    2. Select your preferred connection type and follow the instructions.

    3. When you are finished click Add.

    4. After having confirmed your changes, the newly configured network connection appears in the list of available networks you get by opening the Status Menu.

  3. To edit a connection:

    1. Select the entry to edit.

    2. Click the gear icon to open the Connection Settings dialog.

    3. Insert your changes and click Apply to save them.

    4. To Make your connection available as system connection go to the Identity tab and set the check box Make available to other users. For more information about User and System Connections, see Section 36.4.1, “User and System Connections”.

36.3.1 Managing Wired Network Connections

If your computer is connected to a wired network, use the NetworkManager applet to manage the connection.

  1. Open the Status Menu and click Wired to change the connection details or to switch it off.

  2. To change the settings click Wired Settings and then click the gear icon.

  3. To switch off all network connections, activate the Airplane Mode setting.

36.3.2 Managing Wireless Network Connections

Visible wireless networks are listed in the GNOME NetworkManager applet menu under Wireless Networks. The signal strength of each network is also shown in the menu. Encrypted wireless networks are marked with a shield icon.

Procedure 36.2: Connecting to a visible Wireless Network
  1. To connect to a visible wireless network, open the Status Menu and click Wi-Fi.

  2. Click Turn On to enable it.

  3. Click Select Network, select your Wi-Fi Network and click Connect.

  4. If the network is encrypted, a configuration dialog opens. It shows the type of encryption the network uses and text boxes for entering the login credentials.

Procedure 36.3: Connecting to an Invisible Wireless Network
  1. To connect to a network that does not broadcast its service set identifier (SSID or ESSID) and therefore cannot be detected automatically, open the Status Menu and click Wi-Fi.

  2. Click Wi-Fi Settings to open the detailed settings menu.

  3. Make sure your Wi-Fi is enabled and click Connect to Hidden Network.

  4. In the dialog that opens, enter the SSID or ESSID in Network Name and set encryption parameters if necessary.

A wireless network that has been chosen explicitly will remain connected as long as possible. If a network cable is plugged in during that time, any connections that have been set to Stay connected when possible will be connected, while the wireless connection remains up.

36.3.3 Configuring Your Wi-Fi/Bluetooth Card as an Access Point

If your Wi-Fi/Bluetooth card supports access point mode, you can use NetworkManager for the configuration.

  1. Open the Status Menu and click Wi-Fi.

  2. Click Wi-Fi Settings to open the detailed settings menu.

  3. Click Use as Hotspot and follow the instructions.

  4. Use the credentials shown in the resulting dialog to connect to the hotspot from a remote machine.

36.3.4 NetworkManager and VPN

NetworkManager supports several Virtual Private Network (VPN) technologies. For each technology, SUSE Linux Enterprise Server comes with a base package providing the generic support for NetworkManager. In addition to that, you also need to install the respective desktop-specific package for your applet.

OpenVPN

To use this VPN technology, install:

  • NetworkManager-openvpn

  • NetworkManager-openvpn-gnome

vpnc (Cisco AnyConnect)

To use this VPN technology, install:

  • NetworkManager-vpnc

  • NetworkManager-vpnc-gnome

PPTP (Point-to-Point Tunneling Protocol)

To use this VPN technology, install:

  • NetworkManager-pptp

  • NetworkManager-pptp-gnome

The following procedure describes how to set up your computer as an OpenVPN client using NetworkManager. Setting up other types of VPNs works analogously.

Before you begin, make sure that the package NetworkManager-openvpn-gnome is installed and all dependencies have been resolved.

Procedure 36.4: Setting Up OpenVPN with NetworkManager
  1. Open the application Settings by clicking the status icons at the right end of the panel and clicking the wrench and screwdriver icon. In the window All Settings, choose Network.

  2. Click the + icon.

  3. Select VPN and then OpenVPN.

  4. Choose the Authentication type. Depending on the setup of your OpenVPN server, choose Certificates (TLS) or Password with Certificates (TLS).

  5. Insert the necessary values into the respective text boxes. For our example configuration, these are:

    Gateway

    The remote endpoint of the VPN server

    User name

    The user (only available when you have selected Password with Certificates (TLS))

    Password

    The password for the user (only available when you have selected Password with Certificates (TLS))

    User Certificate

    /etc/openvpn/client1.crt

    CA Certificate

    /etc/openvpn/ca.crt

    Private Key

    /etc/openvpn/client1.key

  6. Finish the configuration with Add.

  7. To enable the connection, in the Network panel of the Settings application click the switch button. Alternatively, click the status icons at the right end of the panel, click the name of your VPN and then Connect.

36.4 NetworkManager and Security

NetworkManager distinguishes two types of wireless connections, trusted and untrusted. A trusted connection is any network that you explicitly selected in the past. All others are untrusted. Trusted connections are identified by the name and MAC address of the access point. Using the MAC address ensures that you cannot use a different access point with the name of your trusted connection.

NetworkManager periodically scans for available wireless networks. If multiple trusted networks are found, the most recently used is automatically selected. NetworkManager waits for your selection in case that all networks are untrusted.

If the encryption setting changes but the name and MAC address remain the same, NetworkManager attempts to connect, but first you are asked to confirm the new encryption settings and provide any updates, such as a new key.

If you switch from using a wireless connection to offline mode, NetworkManager blanks the SSID or ESSID. This ensures that the card is disconnected.

36.4.1 User and System Connections

NetworkManager knows two types of connections: user and system connections. User connections are connections that become available to NetworkManager when the first user logs in. Any required credentials are asked from the user and when the user logs out, the connections are disconnected and removed from NetworkManager. Connections that are defined as system connection can be shared by all users and are made available right after NetworkManager is started—before any users log in. In case of system connections, all credentials must be provided at the time the connection is created. Such system connections can be used to automatically connect to networks that require authorization. For information how to configure user or system connections with NetworkManager, refer to Section 36.3, “Configuring Network Connections”.

36.4.2 Storing Passwords and Credentials

If you do not want to re-enter your credentials each time you want to connect to an encrypted network, you can use the GNOME Keyring Manager to store your credentials encrypted on the disk, secured by a master password.

NetworkManager can also retrieve its certificates for secure connections (for example, encrypted wired, wireless or VPN connections) from the certificate store. For more information, refer to Chapter 12, Certificate Store.

36.5 Frequently Asked Questions

In the following, find some frequently asked questions about configuring special network options with NetworkManager.

How to tie a connection to a specific device?

By default, connections in NetworkManager are device type-specific: they apply to all physical devices with the same type. If more than one physical device per connection type is available (for example, your machine is equipped with two Ethernet cards), you can tie a connection to a certain device.

To do this in GNOME, first look up the MAC address of your device (use the Connection Information available from the applet, or use the output of command line tools like nm-tool or wicked show all). Then start the dialog for configuring network connections and choose the connection you want to modify. On the Wired or Wireless tab, enter the MAC Address of the device and confirm your changes.

How to specify a certain access point in case multiple access points with the same ESSID are detected?

When multiple access points with different wireless bands (a/b/g/n) are available, the access point with the strongest signal is automatically chosen by default. To override this, use the BSSID field when configuring wireless connections.

The Basic Service Set Identifier (BSSID) uniquely identifies each Basic Service Set. In an infrastructure Basic Service Set, the BSSID is the MAC address of the wireless access point. In an independent (ad-hoc) Basic Service Set, the BSSID is a locally administered MAC address generated from a 46-bit random number.

Start the dialog for configuring network connections as described in Section 36.3, “Configuring Network Connections”. Choose the wireless connection you want to modify and click Edit. On the Wireless tab, enter the BSSID.

How to share network connections to other computers?

The primary device (the device which is connected to the Internet) does not need any special configuration. However, you need to configure the device that is connected to the local hub or machine as follows:

  1. Start the dialog for configuring network connections as described in Section 36.3, “Configuring Network Connections”. Choose the connection you want to modify and click Edit. Switch to the IPv4 Settings tab and from the Method drop-down box, activate Shared to other computers. That will enable IP traffic forwarding and run a DHCP server on the device. Confirm your changes in NetworkManager.

  2. As the DCHP server uses port 67, make sure that it is not blocked by the firewall: On the machine sharing the connections, start YaST and select Security and Users › Firewall. Switch to the Allowed Services category. If DCHP Server is not already shown as Allowed Service, select DCHP Server from Services to Allow and click Add. Confirm your changes in YaST.

How to provide static DNS information with automatic (DHCP, PPP, VPN) addresses?

In case a DHCP server provides invalid DNS information (and/or routes), you can override it. Start the dialog for configuring network connections as described in Section 36.3, “Configuring Network Connections”. Choose the connection you want to modify and click Edit. Switch to the IPv4 Settings tab, and from the Method drop-down box, activate Automatic (DHCP) addresses only. Enter the DNS information in the DNS Servers and Search Domains fields. To Ignore automatically obtained routes click Routes and activate the respective check box. Confirm your changes.

How to make NetworkManager connect to password protected networks before a user logs in?

Define a system connection that can be used for such purposes. For more information, refer to Section 36.4.1, “User and System Connections”.

36.6 Troubleshooting

Connection problems can occur. Some common problems related to NetworkManager include the applet not starting or a missing VPN option. Methods for resolving and preventing these problems depend on the tool used.

NetworkManager Desktop Applet Does Not Start

The applets starts automatically if the network is set up for NetworkManager control. If the applet does not start, check if NetworkManager is enabled in YaST as described in Section 36.2, “Enabling or Disabling NetworkManager”. Then make sure that the NetworkManager-gnome package is also installed.

If the desktop applet is installed but is not running for some reason, start it manually. If the desktop applet is installed but is not running for some reason, start it manually with the command nm-applet.

NetworkManager Applet Does Not Include the VPN Option

Support for NetworkManager, applets, and VPN for NetworkManager is distributed in separate packages. If your NetworkManager applet does not include the VPN option, check if the packages with NetworkManager support for your VPN technology are installed. For more information, see Section 36.3.4, “NetworkManager and VPN”.

No Network Connection Available

If you have configured your network connection correctly and all other components for the network connection (router, etc.) are also up and running, it sometimes helps to restart the network interfaces on your computer. To do so, log in to a command line as root and run systemctl restart wickeds.

36.7 For More Information

More information about NetworkManager can be found on the following Web sites and directories:

NetworkManager Project Page

http://projects.gnome.org/NetworkManager/

Package Documentation

Also check out the information in the following directories for the latest information about NetworkManager and the GNOME applet:

  • /usr/share/doc/packages/NetworkManager/,

  • /usr/share/doc/packages/NetworkManager-gnome/.

37 Power Management

  • Filename: pcmcia_apm.xml
  • ID: cha.pmanage

System z The features and hardware described in this chapter do not exist on IBM z Systems, making this chapter irrelevant for these platforms.

Power management is especially important on laptop computers, but is also useful on other systems. ACPI (Advanced Configuration and Power Interface) is available on all modern computers (laptops, desktops, and servers). Power management technologies require suitable hardware and BIOS routines. Most laptops and many modern desktops and servers meet these requirements. It is also possible to control CPU frequency scaling to save power or decrease noise.

37.1 Power Saving Functions

Power saving functions are not only significant for the mobile use of laptops, but also for desktop systems. The main functions and their use in ACPI are:

Standby

not supported.

Suspend (to memory)

This mode writes the entire system state to the RAM. Subsequently, the entire system except the RAM is put to sleep. In this state, the computer consumes very little power. The advantage of this state is the possibility of resuming work at the same point within a few seconds without having to boot and restart applications. This function corresponds to the ACPI state S3.

Hibernation (suspend to disk)

In this operating mode, the entire system state is written to the hard disk and the system is powered off. There must be a swap partition at least as big as the RAM to write all the active data. Reactivation from this state takes about 30 to 90 seconds. The state prior to the suspend is restored. Some manufacturers offer useful hybrid variants of this mode, such as RediSafe in IBM Thinkpads. The corresponding ACPI state is S4. In Linux, suspend to disk is performed by kernel routines that are independent from ACPI.

Note
Note: Changed UUID for Swap Partitions when Formatting via mkswap

Do not reformat existing swap partitions with mkswap if possible. Reformatting with mkswap will change the UUID value of the swap partition. Either reformat via YaST (will update /etc/fstab) or adjust /etc/fstab manually.

Battery Monitor

ACPI checks the battery charge status and provides information about it. Additionally, it coordinates actions to perform when a critical charge status is reached.

Automatic Power-Off

Following a shutdown, the computer is powered off. This is especially important when an automatic shutdown is performed shortly before the battery is empty.

Processor Speed Control

In connection with the CPU, energy can be saved in three different ways: frequency and voltage scaling (also known as PowerNow! or Speedstep), throttling and putting the processor to sleep (C-states). Depending on the operating mode of the computer, these methods can also be combined.

37.2 Advanced Configuration and Power Interface (ACPI)

ACPI was designed to enable the operating system to set up and control the individual hardware components. ACPI supersedes both Power Management Plug and Play (PnP) and Advanced Power Management (APM). It delivers information about the battery, AC adapter, temperature, fan and system events, like close lid or battery low.

The BIOS provides tables containing information about the individual components and hardware access methods. The operating system uses this information for tasks like assigning interrupts or activating and deactivating components. Because the operating system executes commands stored in the BIOS, the functionality depends on the BIOS implementation. The tables ACPI can detect and load are reported in journald. See Chapter 15, journalctl: Query the systemd Journal for more information on viewing the journal log messages. See Section 37.2.2, “Troubleshooting” for more information about troubleshooting ACPI problems.

37.2.1 Controlling the CPU Performance

The CPU can save energy in three ways:

  • Frequency and Voltage Scaling

  • Throttling the Clock Frequency (T-states)

  • Putting the Processor to Sleep (C-states)

Depending on the operating mode of the computer, these methods can be combined. Saving energy also means that the system heats up less and the fans are activated less frequently.

Frequency scaling and throttling are only relevant if the processor is busy, because the most economic C-state is applied anyway when the processor is idle. If the CPU is busy, frequency scaling is the recommended power saving method. Often the processor only works with a partial load. In this case, it can be run with a lower frequency. Usually, dynamic frequency scaling controlled by the kernel on-demand governor is the best approach.

Throttling should be used as the last resort, for example, to extend the battery operation time despite a high system load. However, some systems do not run smoothly when they are throttled too much. Moreover, CPU throttling does not make sense if the CPU has little to do.

For in-depth information, refer to Chapter 11, Power Management.

37.2.2 Troubleshooting

There are two different types of problems. On one hand, the ACPI code of the kernel may contain bugs that were not detected in time. In this case, a solution will be made available for download. More often, the problems are caused by the BIOS. Sometimes, deviations from the ACPI specification are purposely integrated in the BIOS to circumvent errors in the ACPI implementation of other widespread operating systems. Hardware components that have serious errors in the ACPI implementation are recorded in a blacklist that prevents the Linux kernel from using ACPI for these components.

The first thing to do when problems are encountered is to update the BIOS. If the computer does not boot, one of the following boot parameters may be helpful:

pci=noacpi

Do not use ACPI for configuring the PCI devices.

acpi=ht

Only perform a simple resource configuration. Do not use ACPI for other purposes.

acpi=off

Disable ACPI.

Warning
Warning: Problems Booting without ACPI

Some newer machines (especially SMP systems and AMD64 systems) need ACPI for configuring the hardware correctly. On these machines, disabling ACPI can cause problems.

Sometimes, the machine is confused by hardware that is attached over USB or FireWire. If a machine refuses to boot, unplug all unneeded hardware and try again.

Monitor the boot messages of the system with the command dmesg -T | grep -2i acpi (or all messages, because the problem may not be caused by ACPI) after booting. If an error occurs while parsing an ACPI table, the most important table—the DSDT (Differentiated System Description Table)—can be replaced with an improved version. In this case, the faulty DSDT of the BIOS is ignored. The procedure is described in Section 37.4, “Troubleshooting”.

In the kernel configuration, there is a switch for activating ACPI debug messages. If a kernel with ACPI debugging is compiled and installed, detailed information is issued.

If you experience BIOS or hardware problems, it is always advisable to contact the manufacturers. Especially if they do not always provide assistance for Linux, they should be confronted with the problems. Manufacturers will only take the issue seriously if they realize that an adequate number of their customers use Linux.

37.2.2.1 For More Information

37.3 Rest for the Hard Disk

In Linux, the hard disk can be put to sleep entirely if it is not needed or it can be run in a more economic or quieter mode. On modern laptops, you do not need to switch off the hard disks manually, because they automatically enter an economic operating mode whenever they are not needed. However, if you want to maximize power savings, test some of the following methods, using the hdparm command.

It can be used to modify various hard disk settings. The option -y instantly switches the hard disk to the standby mode. -Y puts it to sleep. hdparm -S X causes the hard disk to be spun down after a certain period of inactivity. Replace X as follows: 0 disables this mechanism, causing the hard disk to run continuously. Values from 1 to 240 are multiplied by 5 seconds. Values from 241 to 251 correspond to 1 to 11 times 30 minutes.

Internal power saving options of the hard disk can be controlled with the option -B. Select a value from 0 to 255 for maximum saving to maximum throughput. The result depends on the hard disk used and is difficult to assess. To make a hard disk quieter, use the option -M. Select a value from 128 to 254 for quiet to fast.

Often, it is not so easy to put the hard disk to sleep. In Linux, numerous processes write to the hard disk, waking it up repeatedly. Therefore, it is important to understand how Linux handles data that needs to be written to the hard disk. First, all data is buffered in the RAM. This buffer is monitored by the pdflush daemon. When the data reaches a certain age limit or when the buffer is filled to a certain degree, the buffer content is flushed to the hard disk. The buffer size is dynamic and depends on the size of the memory and the system load. By default, pdflush is set to short intervals to achieve maximum data integrity. It checks the buffer every 5 seconds and writes the data to the hard disk. The following variables are interesting:

/proc/sys/vm/dirty_writeback_centisecs

Contains the delay until a pdflush thread wakes up (in hundredths of a second).

/proc/sys/vm/dirty_expire_centisecs

Defines after which timeframe a dirty page should be written out latest. Default is 3000, which means 30 seconds.

/proc/sys/vm/dirty_background_ratio

Maximum percentage of dirty pages until pdflush begins to write them. Default is 5%.

/proc/sys/vm/dirty_ratio

When the dirty page exceeds this percentage of the total memory, processes are forced to write dirty buffers during their time slice instead of continuing to write.

Warning
Warning: Impairment of the Data Integrity

Changes to the pdflush daemon settings endanger the data integrity.

Apart from these processes, journaling file systems, like Btrfs, Ext3, Ext4 and others write their metadata independently from pdflush, which also prevents the hard disk from spinning down.

Another important factor is the way active programs behave. For example, good editors regularly write hidden backups of the currently modified file to the hard disk, causing the disk to wake up. Features like this can be disabled at the expense of data integrity.

In this connection, the mail daemon postfix uses the variable POSTFIX_LAPTOP. If this variable is set to yes, postfix accesses the hard disk far less frequently.

37.4 Troubleshooting

All error messages and alerts are logged in the system journal that can be queried with the command journalctl (see Chapter 15, journalctl: Query the systemd Journal for more information). The following sections cover the most common problems.

37.4.1 CPU Frequency Does Not Work

Refer to the kernel sources to see if your processor is supported. You may need a special kernel module or module option to activate CPU frequency control. If the kernel-source package is installed, this information is available in /usr/src/linux/Documentation/cpu-freq/*.

37.5 For More Information

Part VI Troubleshooting

38 Help and Documentation

SUSE® Linux Enterprise Server comes with various sources of information and documentation, many of which are already integrated into your installed system.

39 Gathering System Information for Support

For a quick overview of all relevant system information of a machine, SUSE Linux Enterprise Server offers the hostinfo package. It also helps system administrators to check for tainted kernels (that are not supported) or any third-party packages installed on a machine.

In case of problems, a detailed system report may be created with either the supportconfig command line tool or the YaST Support module. Both will collect information about the system such as: current kernel version, hardware, installed packages, partition setup, and much more. The result is a TAR archive of files. After opening a Service Request (SR), you can upload the TAR archive to Global Technical Support. It will help to locate the issue you reported and to assist you in solving the problem.

Additionally, you can analyze the supportconfig output for known issues to help resolve problems faster. For this purpose, SUSE Linux Enterprise Server provides both an appliance and a command line tool for Supportconfig Analysis (SCA).

40 Common Problems and Their Solutions

This chapter describes a range of potential problems and their solutions. Even if your situation is not precisely listed here, there may be one similar enough to offer hints to the solution of your problem.

38 Help and Documentation

  • Filename: help_admin.xml
  • ID: cha.adminhelp

SUSE® Linux Enterprise Server comes with various sources of information and documentation, many of which are already integrated into your installed system.

Documentation in /usr/share/doc

This traditional help directory holds various documentation files and release notes for your system. It contains also information of installed packages in the subdirectory packages. Find more detailed information in Section 38.1, “Documentation Directory”.

Man Pages and Info Pages for Shell Commands

When working with the shell, you do not need to know the options of the commands by heart. Traditionally, the shell provides integrated help by means of man pages and info pages. Read more in Section 38.2, “Man Pages” and Section 38.3, “Info Pages”.

Desktop Help Center

The help center of the GNOME desktop (Help) provides central access to the most important documentation resources on your system in searchable form. These resources include online help for installed applications, man pages, info pages, and the SUSE manuals delivered with your product.

Separate Help Packages for Some Applications

When installing new software with YaST, the software documentation is usually installed automatically and appears in the help center of your desktop. However, some applications, such as GIMP, may have different online help packages that can be installed separately with YaST and do not integrate into the help centers.

38.1 Documentation Directory

The traditional directory to find documentation on your installed Linux system is /usr/share/doc. Usually, the directory contains information about the packages installed on your system, plus release notes, manuals, and more.

Note
Note: Contents Depends on Installed Packages

In the Linux world, many manuals and other kinds of documentation are available in the form of packages, like software. How much and which information you find in /usr/share/docs also depends on the (documentation) packages installed. If you cannot find the subdirectories mentioned here, check if the respective packages are installed on your system and add them with YaST, if needed.

38.1.1 SUSE Manuals

We provide HTML and PDF versions of our books in different languages. In the manual subdirectory, find HTML versions of most of the SUSE manuals available for your product. For an overview of all documentation available for your product refer to the preface of the manuals.

If more than one language is installed, /usr/share/doc/manual may contain different language versions of the manuals. The HTML versions of the SUSE manuals are also available in the help center of both desktops. For information on where to find the PDF and HTML versions of the books on your installation media, refer to the SUSE Linux Enterprise Server Release Notes. They are available on your installed system under /usr/share/doc/release-notes/ or online at your product-specific Web page at http://www.suse.com/releasenotes//.

38.1.2 Package Documentation

Under packages, find the documentation that is included in the software packages installed on your system. For every package, a subdirectory /usr/share/doc/packages/PACKAGENAME is created. It often contains README files for the package and sometimes examples, configuration files, or additional scripts. The following list introduces typical files to be found under /usr/share/doc/packages. None of these entries are mandatory and many packages might only include a few of them.

AUTHORS

List of the main developers.

BUGS

Known bugs or malfunctions. Might also contain a link to a Bugzilla Web page where you can search all bugs.

CHANGES , ChangeLog

Summary of changes from version to version. Usually interesting for developers, because it is very detailed.

COPYING , LICENSE

Licensing information.

FAQ

Question and answers collected from mailing lists or newsgroups.

INSTALL

How to install this package on your system. As the package is already installed by the time you get to read this file, you can safely ignore the contents of this file.

README, README.*

General information on the software. For example, for what purpose and how to use it.

TODO

Things that are not implemented yet, but probably will be in the future.

MANIFEST

List of files with a brief summary.

NEWS

Description of what is new in this version.

38.2 Man Pages

Man pages are an essential part of any Linux system. They explain the usage of a command and all available options and parameters. Man pages can be accessed with man followed by the name of the command, for example, man ls.

Man pages are displayed directly in the shell. To navigate them, move up and down with Page ↑ and Page ↓. Move between the beginning and the end of a document with Home and End. End this viewing mode by pressing Q. Learn more about the man command itself with man man. Man pages are sorted in categories as shown in Table 38.1, “Man Pages—Categories and Descriptions” (taken from the man page for man itself).

Table 38.1: Man Pages—Categories and Descriptions

Number

Description

1

Executable programs or shell commands

2

System calls (functions provided by the kernel)

3

Library calls (functions within program libraries)

4

Special files (usually found in /dev)

5

File formats and conventions (/etc/fstab)

6

Games

7

Miscellaneous (including macro packages and conventions), for example, man(7), groff(7)

8

System administration commands (usually only for root)

9

Kernel routines (nonstandard)

Each man page consists of several parts labeled NAME , SYNOPSIS , DESCRIPTION , SEE ALSO , LICENSING , and AUTHOR . There may be additional sections available depending on the type of command.

38.3 Info Pages

Info pages are another important source of information on your system. Usually, they are more detailed than man pages. They consist of more than command line options and contain sometimes whole tutorials or reference documentation. To view the info page for a certain command, enter info followed by the name of the command, for example, info ls. You can browse an info page with a viewer directly in the shell and display the different sections, called nodes. Use Space to move forward and <— to move backward. Within a node, you can also browse with Page ↑ and Page ↓ but only Space and <— will take you also to the previous or subsequent node. Press Q to end the viewing mode. Not every command comes with an info page and vice versa.

38.4 Online Resources

In addition to the online versions of the SUSE manuals installed under /usr/share/doc, you can also access the product-specific manuals and documentation on the Web. For an overview of all documentation available for SUSE Linux Enterprise Server check out your product-specific documentation Web page at http://www.suse.com/doc/.

If you are searching for additional product-related information, you can also refer to the following Web sites:

SUSE Technical Support

The SUSE Technical Support can be found at http://www.suse.com/support/ if you have questions or need solutions for technical problems.

SUSE Forums

There are several forums where you can dive in on discussions about SUSE products. See http://forums.suse.com/ for a list.

SUSE Conversations

An online community, which offers articles, tips, Q and A, and free tools to download: http://www.suse.com/communities/conversations/

GNOME Documentation

Documentation for GNOME users, administrators and developers is available at http://library.gnome.org/.

The Linux Documentation Project

The Linux Documentation Project (TLDP) is run by a team of volunteers who write Linux-related documentation (see http://www.tldp.org). It is probably the most comprehensive documentation resource for Linux. The set of documents contains tutorials for beginners, but is mainly focused on experienced users and professional system administrators. TLDP publishes HOWTOs, FAQs, and guides (handbooks) under a free license. Parts of the documentation from TLDP are also available on SUSE Linux Enterprise Server.

You can also try general-purpose search engines. For example, use the search terms Linux CD-RW help or OpenOffice file conversion problem if you have trouble with burning CDs or LibreOffice file conversion.

39 Gathering System Information for Support

  • Filename: adm_support.xml
  • ID: cha.adm.support
Abstract

For a quick overview of all relevant system information of a machine, SUSE Linux Enterprise Server offers the hostinfo package. It also helps system administrators to check for tainted kernels (that are not supported) or any third-party packages installed on a machine.

In case of problems, a detailed system report may be created with either the supportconfig command line tool or the YaST Support module. Both will collect information about the system such as: current kernel version, hardware, installed packages, partition setup, and much more. The result is a TAR archive of files. After opening a Service Request (SR), you can upload the TAR archive to Global Technical Support. It will help to locate the issue you reported and to assist you in solving the problem.

Additionally, you can analyze the supportconfig output for known issues to help resolve problems faster. For this purpose, SUSE Linux Enterprise Server provides both an appliance and a command line tool for Supportconfig Analysis (SCA).

39.1 Displaying Current System Information

For a quick and easy overview of all relevant system information when logging in to a server, use the package hostinfo. After it has been installed on a machine, the console displays the following information to any root user that logs in to this machine:

Example 39.1: Output of hostinfo When Logging In as root
Hostname:                 earth
Current As Of:            Wed 12 Mar 2014 03:57:05 PM CET
Distribution:             SUSE Linux Enterprise Server 12
 -Service Pack:           0
Architecture:             x86_64
Kernel Version:           3.12.12-3-default
 -Installed:              Mon 10 Mar 2014 03:15:05 PM CET
 -Status:                 Not Tainted
Last Updated Package:     Wed 12 Mar 2014 03:56:43 PM CET
 -Patches Needed:         0
 -Security:               0
 -3rd Party Packages:     0
IPv4 Address:             ens3 192.168.1.1
Total/Free/+Cache Memory: 983/95/383 MB (38% Free)
Hard Disk:                /dev/sda 10 GB

In case the output shows a tainted kernel status, see Section 39.6, “Support of Kernel Modules” for more details.

39.2 Collecting System Information with Supportconfig

To create a TAR archive with detailed system information that you can hand over to Global Technical Support, use either the supportconfig command line tool directly or the YaST Support module. The command line tool is provided by the package supportutils which is installed by default. The YaST Support module is also based on the command line tool.

39.2.1 Creating a Service Request Number

Supportconfig archives can be generated at any time. However, for handing over the supportconfig data to Global Technical Support, you need to generate a service request number first. You will need it to upload the archive to support.

To create a service request, go to https://scc.suse.com/support/requests and follow the instructions on the screen. Write down your 12-digit service request number.

Note
Note: Privacy Statement

SUSE and Micro Focus treat system reports as confidential data. For details about our privacy commitment, see https://www.suse.com/company/policies/privacy/.

39.2.2 Upload Targets

After having created a service request number, you can upload your supportconfig archives to Global Technical Support as described in Procedure 39.1, “Submitting Information to Support with YaST” or Procedure 39.2, “Submitting Information to Support from Command Line”. Use one of the following upload targets:

Alternatively, you can manually attach the TAR archive to your service request using the service request URL: https://scc.suse.com/support/requests.

39.2.3 Creating a Supportconfig Archive with YaST

To use YaST to gather your system information, proceed as follows:

  1. Start YaST and open the Support module.

  2. Click Create report tarball.

  3. In the next window, select one of the supportconfig options from the radio button list. Use Custom (Expert) Settings is preselected by default. If you want to test the report function first, use Only gather a minimum amount of info. For some background information on the other options, refer to the supportconfig man page.

    Proceed with Next.

  4. Enter your contact information. It will be written to a file called basic-environment.txt and included in the archive to be created.

  5. If you want to submit the archive to Global Technical Support at the end of the information collection process, Upload Information is required. YaST automatically proposes an upload server. If you want to modify it, refer to Section 39.2.2, “Upload Targets” for details of which upload servers are available.

    If you want to submit the archive later on, you can leave the Upload Information empty for now.

  6. Proceed with Next.

  7. The information gathering begins.

    After the process is finished, continue with Next.

  8. Review the data collection: Select the File Name of a log file to view its contents in YaST. To remove any files you want excluded from the TAR archive before submitting it to support, use Remove from Data. Continue with Next.

  9. Save the TAR archive. If you started the YaST module as root user, by default YaST proposes to save the archive to /var/log (otherwise, to your home directory). The file name format is nts_HOST_DATE_TIME.tbz.

  10. If you want to upload the archive to support directly, make sure Upload log files tarball to URL is activated. The Upload Target shown here is the one that YaST proposes in Step 5. If you want to modify the upload target, find detailed information of which upload servers are available in Section 39.2.2, “Upload Targets”.

  11. If you want to skip the upload, deactivate Upload log files tarball to URL.

  12. Confirm your changes to close the YaST module.

39.2.4 Creating a Supportconfig Archive from Command Line

The following procedure shows how to create a supportconfig archive, but without submitting it to support directly. For uploading it, you need to run the command with certain options as described in Procedure 39.2, “Submitting Information to Support from Command Line”.

  1. Open a shell and become root.

  2. Run supportconfig without any options. This gathers the default system information.

  3. Wait for the tool to complete the operation.

  4. The default archive location is /var/log, with the file name format being nts_HOST_DATE_TIME.tbz

39.2.5 Common Supportconfig Options

The supportconfig utility is usually called without any options. Display a list of all options with supportconfig -h or refer to the man page. The following list gives a brief overview of some common use cases:

Reducing the Size of the Information Being Gathered

Use the minimal option (-m):

supportconfig -m
Limiting the Information to a Specific Topic

If you have already localized a problem with the default supportconfig output and have found that it relates to a specific area or feature set only, you should limit the collected information to the specific area for the next supportconfig run. For example, if you detected problems with LVM and want to test a recent change that you did to the LVM configuration, it makes sense to gather the minimum supportconfig information around LVM only:

supportconfig -i LVM

For a complete list of feature keywords that you can use for limiting the collected information to a specific area, run

supportconfig -F
Including Additional Contact Information in the Output:
supportconfig -E tux@example.org -N "Tux Penguin" -O "Penguin Inc." ...

(all in one line)

Collecting Already Rotated Log Files
supportconfig -l

This is especially useful in high logging environments or after a kernel crash when syslog rotates the log files after a reboot.

39.3 Submitting Information to Global Technical Support

Use the YaST Support module or the supportconfig command line utility to submit system information to the Global Technical Support. When you experience a server issue and want the support's assistance, you will need to open a service request first. For details, see Section 39.2.1, “Creating a Service Request Number”.

The following examples use 12345678901 as a placeholder for your service request number. Replace 12345678901 with the service request number you created in Section 39.2.1, “Creating a Service Request Number”.

Procedure 39.1: Submitting Information to Support with YaST

The following procedure assumes that you have already created a supportconfig archive, but have not uploaded it yet. Make sure to have included your contact information in the archive as described in Section 39.2.3, “Creating a Supportconfig Archive with YaST”, Step 4. For instructions on how to generate and submit a supportconfig archive in one go, see Section 39.2.3, “Creating a Supportconfig Archive with YaST”.

  1. Start YaST and open the Support module.

  2. Click Upload.

  3. In Package with log files specify the path to the existing supportconfig archive or Browse for it.

  4. YaST automatically proposes an upload server. If you want to modify it, refer to Section 39.2.2, “Upload Targets” for details of which upload servers are available.

    Proceed with Next.

  5. Click Finish.

Procedure 39.2: Submitting Information to Support from Command Line

The following procedure assumes that you have already created a supportconfig archive, but have not uploaded it yet. For instructions on how to generate and submit a supportconfig archive in one go, see Section 39.2.3, “Creating a Supportconfig Archive with YaST”.

  1. Servers with Internet connectivity:

    1. To use the default upload target, run:

      supportconfig -ur 12345678901
    2. For the secure upload target, use the following:

      supportconfig -ar 12345678901
  2. Servers without Internet connectivity

    1. Run the following:

      supportconfig -r 12345678901
    2. Manually upload the /var/log/nts_SR12345678901*tbz archive to one of our FTP servers. Which one to use depends on your location in the world. For an overview, see Section 39.2.2, “Upload Targets”.

  3. After the TAR archive arrives in the incoming directory of our FTP server, it becomes automatically attached to your service request.

39.4 Analyzing System Information

System reports created with supportconfig can be analyzed for known issues to help resolve problems faster. For this purpose, SUSE Linux Enterprise Server provides both an appliance and a command line tool for Supportconfig Analysis (SCA). The SCA appliance is a server-side tool which is non-interactive. The SCA tool (scatool) runs on the client-side and is executed from command line. Both tools analyze supportconfig archives from affected servers. The initial server analysis takes place on the SCA appliance or the workstation on which scatool is running. No analysis cycles happen on the production server.

Both the appliance and the command line tool additionally need product-specific patterns that enable them to analyze the supportconfig output for the associated products. Each pattern is a script that parses and evaluates a supportconfig archive for one known issue. The patterns are available as RPM packages.

For example, if you want to analyze supportconfig archives that have been generated on a SUSE Linux Enterprise 11 machine, you need to install the package sca-patterns-sle11 together with the SCA tool (or on the machine that you want to use as the SCA appliance server). To analyze supportconfig archives generated on a SUSE Linux Enterprise 10 machine, you need the package sca-patterns-sle10.

You can also develop your own patterns as briefly described in Section 39.4.3, “Developing Custom Analysis Patterns”.

39.4.1 SCA Command Line Tool

The SCA command line tool lets you analyze a local machine using both supportconfig and the analysis patterns for the specific product that is installed on the local machine. The tool creates an HTML report showing its analysis results. For an example, see Figure 39.1, “HTML Report Generated by SCA Tool”.

HTML Report Generated by SCA Tool
Figure 39.1: HTML Report Generated by SCA Tool

The scatool command is provided by the sca-server-report package. It is not installed by default. Additionally, you need the sca-patterns-base package and any of the product-specific sca-patterns-* packages that matches the product installed on the machine where you want to run the scatool command.

Execute the scatool command either as root user or with sudo. When calling the SCA tool, you can either analyze an existing supportconfig TAR archive or you can let it generate and analyze a new archive in one go. The tool also provides an interactive console (with tab completion) and the possibility to run supportconfig on an external machine and to execute the subsequent analysis on the local machine.

Find some example commands below:

sudo scatool-s

Calls supportconfig and generates a new supportconfig archive on the local machine. Analyzes the archive for known issues by applying the SCA analysis patterns that match the installed product. Displays the path to the HTML report that is generated from the results of the analysis. It is usually written to the same directory where the supportconfig archive can be found.

sudo scatool -s -o /opt/sca/reports/ 

Same as sudo scatool -s, only that the HTML report is written to the path specified with -o.

sudo scatool -a PATH_TO_TARBALL_OR_DIR 

Analyzes the specified supportconfig archive file (or the specified directory to where the supportconfig archive has been extracted). The generated HTML report is saved in the same location as the supportconfig archive or directory.

sudo scatool -a SLES_SERVER.COMPANY.COM 

Establishes an SSH connection to an external server SLES_SERVER.COMPANY.COM and runs supportconfig on the server. The supportconfig archive is then copied back to the local machine and is analyzed there. The generated HTML report is saved to the default /var/log directory. (Only the supportconfig archive is created on SLES_SERVER.COMPANY.COM).

sudo scatool-c

Starts the interactive console for scatool. Press →| twice to see the available commands.

For further options and information, run sudo scatool -h or see the scatool man page.

39.4.2 SCA Appliance

If you decide to use the SCA appliance for analyzing the supportconfig archives, you need to configure a dedicated server (or virtual machine) as the SCA appliance server. The SCA appliance server can then be used to analyze supportconfig archives from all machines in your enterprise running SUSE Linux Enterprise Server or SUSE Linux Enterprise Desktop. You can simply upload supportconfig archives to the appliance server for analysis. Interaction is not required. In a MariaDB database, the SCA appliance keeps track of all supportconfig archives that have been analyzed . You can read the SCA reports directly from the appliance Web interface. Alternatively, you can have the appliance send the HTML report to any administrative user via e-mail. For details, see Section 39.4.2.5.4, “Sending SCA Reports via E-Mail”.

39.4.2.1 Installation Quick Start

To install and set up the SCA appliance in a very fast way from the command line, follow the instructions here. The procedure is intended for experts and focuses on the bare installation and setup commands. For more information, refer to the more detailed description in Section 39.4.2.2, “Prerequisites” to Section 39.4.2.3, “Installation and Basic Setup”.

Prerequisites
  • Web and LAMP Pattern

  • Web and Scripting Module (you must register the machine to be able to select this module).

Note
Note: root Privileges Required

All commands in the following procedure must be run as root.

Procedure 39.3: Installation Using Anonymous FTP for Upload

After the appliance is set up and running, no more manual interaction is required. This way of setting up the appliance is therefore ideal for using cron jobs to create and upload supportconfig archives.

  1. On the machine on which to install the appliance, log in to a console and execute the following commands:

    zypper install sca-appliance-* sca-patterns-* vsftpd
    systemctl enable apache2
    systemctl start apache2
    systemctl enable vsftpd
    systemctl start vsftpd
    yast ftp-server
  2. In YaST FTP Server, select Authentication › Enable Upload › Anonymous Can Upload › Finish › Yes to Create /srv/ftp/upload.

  3. Execute the following commands:

    systemctl enable mysql
    systemctl start mysql
    mysql_secure_installation
    setup-sca -f

    The mysql_secure_installation will create a MariaDB root password.

Procedure 39.4: Installation Using SCP/tmp for Upload

This way of setting up the appliance requires manual interaction when typing the SSH password.

  1. On the machine on which to install the appliance, log in to a console.

  2. Execute the following commands:

    zypper install sca-appliance-* sca-patterns-*
    systemctl enable apache2
    systemctl start apache2
    sudo systemctl enable mysql
    systemctl start mysql
    mysql_secure_installation
    setup-sca

39.4.2.2 Prerequisites

To run an SCA appliance server, you need the following prerequisites:

  • All sca-appliance-* packages.

  • The sca-patterns-base package. Additionally, any of the product-specific sca-patterns-* for the type of supportconfig archives that you want to analyze with the appliance.

  • Apache

  • PHP

  • MariaDB

  • anonymous FTP server (optional)

39.4.2.3 Installation and Basic Setup

As listed in Section 39.4.2.2, “Prerequisites”, the SCA appliance has several dependencies on other packages. Therefore you need do so some preparations before installing and setting up the SCA appliance server:

  1. For Apache and MariaDB, install the Web and LAMP installation patterns.

  2. Set up Apache, MariaDB, and optionally an anonymous FTP server. For more information, see Chapter 31, The Apache HTTP Server and Chapter 32, Setting Up an FTP Server with YaST.

  3. Configure Apache and MariaDB to start at boot time:

    sudo systemctl enable apache2 mysql
  4. Start both services:

    sudo systemctl start apache2 mysql

Now you can install the SCA appliance and set it up as described in Procedure 39.5, “Installing and Configuring the SCA Appliance”.

Procedure 39.5: Installing and Configuring the SCA Appliance

After installing the packages, use the setup-sca script for the basic configuration of the MariaDB administration and report database that is used by the SCA appliance.

It can be used to configure the following options you have for uploading the supportconfig archives from your machines to the SCA appliance:

  • scp

  • anonymous FTP server

  1. Install the appliance and the SCA base-pattern library:

    sudo zypper install sca-appliance-* sca-patterns-base
  2. Additionally, install the pattern packages for the types of supportconfig archives you want to analyze. For example, if you have SUSE Linux Enterprise Server 11 and SUSE Linux Enterprise Server 12 servers in your environment, install both the sca-patterns-sle11 and sca-patterns-sle12 packages.

    To install all available patterns:

    zypper install sca-patterns-*
  3. For basic setup of the SCA appliance, use the setup-sca script. How to call it depends on how you want to upload the supportconfig archives to the SCA appliance server:

    • If you have configured an anonymous FTP server that uses the /srv/ftp/upload directory, execute the setup script with the -f option and follow the instructions on the screen:

      setup-sca -f
      Note
      Note: FTP Server Using Another Directory

      If your FTP server uses another directory than /srv/ftp/upload, adjust the following configuration files first to make them point to the correct directory: /etc/sca/sdagent.conf and /etc/sca/sdbroker.conf .

    • If you want to upload supportconfig files to the /tmp directory of the SCA appliance server via scp, call the setup script without any parameters and follow the instructions on the screen:

      setup-sca

    The setup script runs a few checks regarding its requirements and configures the needed components. It will prompt you for two passwords: the MySQL root password of the MariaDB that you have set up, and a Web user password with which to log in to the Web interface of the SCA appliance.

  4. Enter the existing MariaDB root password. It will allow the SCA appliance to connect to the MariaDB.

  5. Define a password for the Web user. It will be written to /srv/www/htdocs/sca/web-config.php and will be set as the password for the user scdiag. Both user name and password can be changed at any time later, see Section 39.4.2.5.1, “Password for the Web Interface”.

After successful installation and setup, the SCA appliance is ready for use, see Section 39.4.2.4, “Using the SCA Appliance”. However, you should modify some options such as changing the password for the Web interface, changing the source for the SCA pattern updates, enabling archiving mode or configuring e-mail notifications. For details on that, see Section 39.4.2.5, “Customizing the SCA Appliance”.

Warning
Warning: Data Protection

As the reports on the SCA appliance server contain security-relevant information of the machines whose supportconfig archives have been analyzed, make sure to protect the data on the SCA appliance server against unauthorized access.

39.4.2.4 Using the SCA Appliance

You can upload existing supportconfig archives to the SCA appliance manually or create new supportconfig archives and upload them to the SCA appliance in one step. Uploading can be done via FTP or SCP. For both, you need to know the URL where the SCA appliance can be reached. For upload via FTP, an FTP server needs to be configured for the SCA appliance, see Procedure 39.5, “Installing and Configuring the SCA Appliance”.

39.4.2.4.1 Uploading Supportconfig Archives to the SCA Appliance
  • For creating a supportconfig archive and uploading it via (anonymous) FTP:

    sudo supportconfig -U “ftp://SCA-APPLIANCE.COMPANY.COM/upload”
  • For creating a supportconfig archive and uploading it via SCP:

    sudo supportconfig -U “scp://SCA-APPLIANCE.COMPANY.COM/tmp”

    You will be prompted for the root user password of the server running the SCA appliance.

  • If you want to manually upload one or multiple archives, copy the existing archive files (usually located at/var/log/nts_*.tbz) to the SCA appliance. As target, use either the appliance server's /tmp directory or the /srv/ftp/upload directory (if FTP is configured for the SCA appliance server).

39.4.2.4.2 Viewing SCA Reports

SCA reports can be viewed from any machine that has a browser installed and can access the report index page of the SCA appliance.

  1. Start a Web browser and make sure that JavaScript and cookies are enabled.

  2. As a URL, enter the report index page of the SCA appliance.

    https://sca-appliance.company.com/sca

    If in doubt, ask your system administrator.

  3. You will be prompted for a user name and a password to log in.

    HTML Report Generated by SCA Appliance
    Figure 39.2: HTML Report Generated by SCA Appliance
  4. After logging in, click the date of the report you want to read.

  5. Click the Basic Health category first to expand it.

  6. In the Message column, click an individual entry. This opens the corresponding article in the SUSE Knowledgebase. Read the proposed solution and follow the instructions.

  7. If the Solutions column of the Supportconfig Analysis Report shows any additional entries, click them. Read the proposed solution and follow the instructions.

  8. Check the SUSE Knowledgebase (http://www.suse.com/support/kb/) for results that directly relate to the problem identified by SCA. Work at resolving them.

  9. Check for results that can be addressed proactively to avoid future problems.

39.4.2.5 Customizing the SCA Appliance

The following sections show how to change the password for the Web interface, how to change the source for the SCA pattern updates, how to enable archiving mode, and how to configure e-mail notifications.

39.4.2.5.1 Password for the Web Interface

The SCA Appliance Web interface requires a user name and password for logging in. The default user name is scdiag and the default password is linux (if not specified otherwise, see Procedure 39.5, “Installing and Configuring the SCA Appliance”). Change the default password to a secure password at the earliest possibility. You can also modify the user name.

Procedure 39.6: Changing User Name or Password for the Web Interface
  1. Log in as root user at the system console of the SCA appliance server.

  2. Open /srv/www/htdocs/sca/web-config.php in an editor.

  3. Change the values of $username and $password as desired.

  4. Save the file and exit.

39.4.2.5.2 Updates of SCA Patterns

By default, all sca-patterns-* packages are updated regularly by a root cron job that executes the sdagent-patterns script nightly, which in turn runs zypper update sca-patterns-*. A regular system update will update all SCA appliance and pattern packages. To update the SCA appliance and patterns manually, run:

sudo zypper update sca-*

The updates are installed from the SUSE Linux Enterprise 12 SP3 update repository by default. You can change the source for the updates to an SMT server, if desired. When sdagent-patterns runs zypper update sca-patterns-*, it gets the updates from the currently configured update channel. If that channel is located on an SMT server, the packages will be pulled from there.

Procedure 39.7: Disabling Automatic Updates of SCA Patterns
  1. Log in as root user at the system console of the SCA appliance server.

  2. Open /etc/sca/sdagent-patterns.conf in an editor.

  3. Change the entry

    UPDATE_FROM_PATTERN_REPO=1

    to

    UPDATE_FROM_PATTERN_REPO=0
  4. Save the file and exit. The machine does not require any restart to apply the change.

39.4.2.5.3 Archiving Mode

All supportconfig archives are deleted from the SCA appliance after they have been analyzed and their results have been stored in the MariaDB database. However, for troubleshooting purposes it can be useful to keep copies of supportconfig archives from a machine. By default, archiving mode is disabled.

Procedure 39.8: Enabling Archiving Mode in the SCA Appliance
  1. Log in as root user at the system console of the SCA appliance server.

  2. Open /etc/sca/sdagent.conf in an editor.

  3. Change the entry

    ARCHIVE_MODE=0

    to

    ARCHIVE_MODE=1
  4. Save the file and exit. The machine does not require any restart to apply the change.

After having enabled archive mode, the SCA appliance will save the supportconfig files to the /var/log/archives/saved directory, instead of deleting them.

39.4.2.5.4 Sending SCA Reports via E-Mail

The SCA appliance can e-mail a report HTML file for each supportconfig analyzed. This feature is disabled by default. When enabling it, you can define a list of e-mail addresses to which the reports should be sent, and define a level of status messages that trigger the sending of reports (STATUS_NOTIFY_LEVEL).

Possible Values for STATUS_NOTIFY_LEVEL
$STATUS_OFF

Deactivate sending of HTML reports.

$STATUS_CRITICAL

Send only SCA reports that include a CRITICAL.

$STATUS_WARNING

Send only SCA reports that include a WARNING or CRITICAL.

$STATUS_RECOMMEND

Send only SCA reports that include a RECOMMEND, WARNING or CRITICAL.

$STATUS_SUCCESS

Send SCA reports that include a SUCCESS, RECOMMEND, WARNING or CRITICAL.

Procedure 39.9: Configuring E-Mail Notifications for SCA Reports
  1. Log in as root user at the system console of the SCA appliance server.

  2. Open /etc/sca/sdagent.conf in an editor.

  3. Search for the entry STATUS_NOTIFY_LEVEL. By default, it is set to $STATUS_OFF (e-mail notifications are disabled).

  4. To enable e-mail notifications, change $STATUS_OFF to the level of status messages that you want to have e-mail reports for, for example:

    STATUS_NOTIFY_LEVEL=$STATUS_SUCCESS

    For details, see Possible Values for STATUS_NOTIFY_LEVEL.

  5. To define the list of recipients to which the reports should be sent:

    1. Search for the entry EMAIL_REPORT='root'.

    2. Replace root with a list of e-mail addresses to which SCA reports should be sent. The e-mail addresses must be separated by spaces. For example:

      EMAIL_REPORT='tux@my.company.com wilber@your.company.com'
  6. Save the file and exit. The machine does not require any restart to apply the changes. All future SCA reports will be e-mailed to the specified addresses.

39.4.2.6 Backing Up and Restoring the Database

To back up and restore the MariaDB database that stores the SCA reports, use the scadb command as described below.

Procedure 39.10: Backing Up the Database
  1. Log in as root user at the system console of the server running the SCA appliance.

  2. Put the appliance into maintenance mode by executing:

    scadb maint
  3. Start the backup with:

    scadb backup

    The data is saved to a TAR archive: sca-backup-*sql.gz.

  4. If you are using the pattern creation database to develop your own patterns (see Section 39.4.3, “Developing Custom Analysis Patterns”), back up this data, too:

    sdpdb backup

    The data is saved to a TAR archive: sdp-backup-*sql.gz.

  5. Copy the following data to another machine or an external storage medium:

    • sca-backup-*sql.gz

    • sdp-backup-*sql.gz

    • /usr/lib/sca/patterns/local (only needed if you have created custom patterns)

  6. Reactivate the SCA appliance with:

    scadb reset agents
Procedure 39.11: Restoring the Database

To restore the database from your backup, proceed as follows:

  1. Log in as root user at the system console of the server running the SCA appliance.

  2. Copy the newest sca-backup-*sql.gz and sdp-backup-*sql.gz TAR archives to the SCA appliance server.

  3. To decompress the files, run:

    gzip -d *-backup-*sql.gz
  4. To import the data into the database, execute:

    scadb import sca-backup-*sql
  5. If you are using the pattern creation database to create your own patterns, also import the following data with:

    sdpdb import sdp-backup-*sql
  6. If you are using custom patterns, also restore /usr/lib/sca/patterns/local from your backup data.

  7. Reactivate the SCA appliance with:

    scadb reset agents
  8. Update the pattern modules in the database with:

    sdagent-patterns -u

39.4.3 Developing Custom Analysis Patterns

The SCA appliance comes with a complete pattern development environment (the SCA Pattern Database) that enables you to develop your own, custom patterns. Patterns can be written in any programming language. To make them available for the supportconfig analysis process, they need to be saved to /usr/lib/sca/patterns/local and to be made executable. Both the SCA appliance and the SCA tool will then run the custom patterns against new supportconfig archives as part of the analysis report. For detailed instructions on how to create (and test) your own patterns, see http://www.suse.com/communities/conversations/sca-pattern-development/.

39.5 Gathering Information during the Installation

During the installation, supportconfig is not available. However, you can collect log files from YaST by using save_y2logs. This command will create a .tar.xz archive in the directory /tmp.

If issues appear very early during installation, you may be able to gather information from the log file created by linuxrc. linuxrc is a small command that runs before YaST starts. This log file is available at /var/log/linuxrc.log.

Important
Important: Installation Log Files Not Available in the Installed System

The log files available during the installation are not available in the installed system anymore. Properly save the installation log files while the installer is still running.

39.6 Support of Kernel Modules

An important requirement for every enterprise operating system is the level of support you receive for your environment. Kernel modules are the most relevant connector between hardware (controllers) and the operating system. Every kernel module in SUSE Linux Enterprise has a supported flag that can take three possible values:

  • yes, thus supported

  • external, thus supported

  • (empty, not set), thus unsupported

The following rules apply:

  • All modules of a self-recompiled kernel are by default marked as unsupported.

  • Kernel modules supported by SUSE partners and delivered using SUSE SolidDriver Program are marked external.

  • If the supported flag is not set, loading this module will taint the kernel. Tainted kernels are not supported. Unsupported Kernel modules are included in an extra RPM package (kernel-FLAVOR-extra) that is only available for SUSE Linux Enterprise Desktop and the SUSE Linux Enterprise Workstation Extension. Those kernels will not be loaded by default (FLAVOR=default|xen|...). In addition, these unsupported modules are not available in the installer, and the kernel-FLAVOR-extra package is not part of the SUSE Linux Enterprise media.

  • Kernel modules not provided under a license compatible to the license of the Linux kernel will also taint the kernel. For details, see /usr/src/linux/Documentation/sysctl/kernel.txt and the state of /proc/sys/kernel/tainted.

39.6.1 Technical Background

  • Linux kernel: The value of /proc/sys/kernel/unsupported defaults to 2 on SUSE Linux Enterprise 12 SP3 (do not warn in syslog when loading unsupported modules). This default is used in the installer and in the installed system. See /usr/src/linux/Documentation/sysctl/kernel.txt for more information.

  • modprobe: The modprobe utility for checking module dependencies and loading modules appropriately checks for the value of the supported flag. If the value is yes or external the module will be loaded, otherwise it will not. For information on how to override this behavior, see Section 39.6.2, “Working with Unsupported Modules”.

    Note
    Note: Support

    SUSE does not generally support the removal of storage modules via modprobe -r.

39.6.2 Working with Unsupported Modules

While general supportability is important, situations can occur where loading an unsupported module is required (for example, for testing or debugging purposes, or if your hardware vendor provides a hotfix).

  • To override the default, edit /etc/modprobe.d/10-unsupported-modules.conf and change the value of the variable allow_unsupported_modules to 1. If an unsupported module is needed in the initrd, do not forget to run dracut -f to update the initrd.

    If you only want to try loading a module once, you can use the --allow-unsupported-modules option with modprobe. For more information, see the modprobe man page.

  • During installation, unsupported modules may be added through driver update disks, and they will be loaded. To enforce loading of unsupported modules during boot and afterward, use the kernel command line option oem-modules. While installing and initializing the suse-module-tools package, the kernel flag TAINT_NO_SUPPORT (/proc/sys/kernel/tainted) will be evaluated. If the kernel is already tainted, allow_unsupported_modules will be enabled. This will prevent unsupported modules from failing in the system being installed. If no unsupported modules are present during installation and the other special kernel command line option (oem-modules=1) is not used, the default still is to disallow unsupported modules.

Remember that loading and running unsupported modules will make the kernel and the whole system unsupported by SUSE.

39.7 For More Information

40 Common Problems and Their Solutions

  • Filename: troubleshooting.xml
  • ID: cha.trouble

This chapter describes a range of potential problems and their solutions. Even if your situation is not precisely listed here, there may be one similar enough to offer hints to the solution of your problem.

40.1 Finding and Gathering Information

Linux reports things in a very detailed way. There are several places to look when you encounter problems with your system, most of which are standard to Linux systems in general, and some are relevant to SUSE Linux Enterprise Server systems. Most log files can be viewed with YaST (Miscellaneous › Start-Up Log).

YaST offers the possibility to collect all system information needed by the support team. Use Other › Support and select the problem category. When all information is gathered, attach it to your support request.

A list of the most frequently checked log files follows with the description of their typical purpose. Paths containing ~ refer to the current user's home directory.

Table 40.1: Log Files

Log File

Description

~/.xsession-errors

Messages from the desktop applications currently running.

/var/log/apparmor/

Log files from AppArmor, see Part IV, “Confining Privileges with AppArmor for detailed information.

/var/log/audit/audit.log

Log file from Audit to track any access to files, directories, or resources of your system, and trace system calls. See Part VI, “The Linux Audit Framework for detailed information.

/var/log/mail.*

Messages from the mail system.

/var/log/NetworkManager

Log file from NetworkManager to collect problems with network connectivity

/var/log/samba/

Directory containing Samba server and client log messages.

/var/log/warn

All messages from the kernel and system log daemon with the warning level or higher.

/var/log/wtmp

Binary file containing user login records for the current machine session. View it with last.

/var/log/Xorg.*.log

Various start-up and runtime log files from the X Window System. It is useful for debugging failed X start-ups.

/var/log/YaST2/

Directory containing YaST's actions and their results.

/var/log/zypper.log

Log file of Zypper.

Apart from log files, your machine also supplies you with information about the running system. See Table 40.2: System Information With the /proc File System

Table 40.2: System Information With the /proc File System

File

Description

/proc/cpuinfo

Contains processor information, including its type, make, model, and performance.

/proc/dma

Shows which DMA channels are currently being used.

/proc/interrupts

Shows which interrupts are in use, and how many of each have been in use.

/proc/iomem

Displays the status of I/O (input/output) memory.

/proc/ioports

Shows which I/O ports are in use at the moment.

/proc/meminfo

Displays memory status.

/proc/modules

Displays the individual modules.

/proc/mounts

Displays devices currently mounted.

/proc/partitions

Shows the partitioning of all hard disks.

/proc/version

Displays the current version of Linux.

Apart from the /proc file system, the Linux kernel exports information with the sysfs module, an in-memory file system. This module represents kernel objects, their attributes and relationships. For more information about sysfs, see the context of udev in Chapter 21, Dynamic Kernel Device Management with udev. Table 40.3 contains an overview of the most common directories under /sys.

Table 40.3: System Information With the /sys File System

File

Description

/sys/block

Contains subdirectories for each block device discovered in the system. Generally, these are mostly disk type devices.

/sys/bus

Contains subdirectories for each physical bus type.

/sys/class

Contains subdirectories grouped together as a functional types of devices (like graphics, net, printer, etc.)

/sys/device

Contains the global device hierarchy.

Linux comes with several tools for system analysis and monitoring. See Chapter 2, System Monitoring Utilities for a selection of the most important ones used in system diagnostics.

Each of the following scenarios begins with a header describing the problem followed by a paragraph or two offering suggested solutions, available references for more detailed solutions, and cross-references to other scenarios that are related.

40.2 Installation Problems

Installation problems are situations when a machine fails to install. It may fail entirely or it may not be able to start the graphical installer. This section highlights some typical problems you may run into, and offers possible solutions or workarounds for these kinds of situations.

40.2.1 Checking Media

If you encounter any problems using the SUSE Linux Enterprise Server installation media, check the integrity of your installation media. Boot from the media and choose Check Installation Media from the boot menu. In a running system, start YaST and choose Software › Media Check. To check the SUSE Linux Enterprise Server medium, insert it into the drive and click Start Check in the Media Check screen of YaST. This may take several minutes. If errors are detected, do not use this medium for installation. Media problems may occur when having burned the medium yourself. Burning the media at a low speed (4x) helps to avoid problems.

Checking Media
Figure 40.1: Checking Media

40.2.2 No Bootable DVD Drive Available

If your computer does not contain a bootable DVD-ROM drive or if the one you have is not supported by Linux, there are several options you can install your machine without a built-in DVD drive:

Using an External Boot Device

If it is supported by your BIOS and the installation kernel, boot from external DVD drives or USB storage devices. Refer to Section 6.2.2, “PC (AMD64/Intel 64/ARM AArch64): System Start-up” for instructions on how to create a bootable USB storage device.

Network Boot via PXE

If a machine lacks a DVD drive, but provides a working Ethernet connection, perform a completely network-based installation. See Section 10.1.3, “Remote Installation via VNC—PXE Boot and Wake on LAN” and Section 10.1.6, “Remote Installation via SSH—PXE Boot and Wake on LAN” for details.

40.2.2.1 External Boot Devices

Linux supports most existing DVD drives. If the system has no DVD drive, it is still possible that an external DVD drive, connected through USB, FireWire, or SCSI, can be used to boot the system. This depends mainly on the interaction of the BIOS and the hardware used. Sometimes a BIOS update may help if you encounter problems.

When installing from a Live CD, you can also create a Live flash disk to boot from.

40.2.3 Booting from Installation Media Fails

One reason a machine does not boot the installation media can be an incorrect boot sequence setting in BIOS. The BIOS boot sequence must have DVD drive set as the first entry for booting. Otherwise the machine would try to boot from another medium, typically the hard disk. Guidance for changing the BIOS boot sequence can be found the documentation provided with your mainboard, or in the following paragraphs.

The BIOS is the software that enables the very basic functions of a computer. Motherboard vendors provide a BIOS specifically made for their hardware. Normally, the BIOS setup can only be accessed at a specific time—when the machine is booting. During this initialization phase, the machine performs several diagnostic hardware tests. One of them is a memory check, indicated by a memory counter. When the counter appears, look for a line, usually below the counter or somewhere at the bottom, mentioning the key to press to access the BIOS setup. Usually the key to press is one of Del, F1, or Esc. Press this key until the BIOS setup screen appears.

Procedure 40.1: Changing the BIOS Boot Sequence
  1. Enter the BIOS using the proper key as announced by the boot routines and wait for the BIOS screen to appear.

  2. To change the boot sequence in an AWARD BIOS, look for the BIOS FEATURES SETUP entry. Other manufacturers may have a different name for this, such as ADVANCED CMOS SETUP. When you have found the entry, select it and confirm with Enter.

  3. In the screen that opens, look for a subentry called BOOT SEQUENCE or BOOT ORDER. Change the settings by pressing Page ↑ or Page ↓ until the DVD drive is listed first.

  4. Leave the BIOS setup screen by pressing Esc. To save the changes, select SAVE & EXIT SETUP, or press F10. To confirm that your settings should be saved, press Y.

Procedure 40.2: Changing the Boot Sequence in an SCSI BIOS (Adaptec Host Adapter)
  1. Open the setup by pressing CtrlA.

  2. Select Disk Utilities. The connected hardware components are now displayed.

    Make note of the SCSI ID of your DVD drive.

  3. Exit the menu with Esc.

  4. Open Configure Adapter Settings. Under Additional Options, select Boot Device Options and press Enter.

  5. Enter the ID of the DVD drive and press Enter again.

  6. Press Esc twice to return to the start screen of the SCSI BIOS.

  7. Exit this screen and confirm with Yes to boot the computer.

Regardless of what language and keyboard layout your final installation will be using, most BIOS configurations use the US keyboard layout as shown in the following figure:

US Keyboard Layout
Figure 40.2: US Keyboard Layout

40.2.4 Fails to Boot

Some hardware types, mainly very old or very recent ones, fail to install. Often this may happen because support for this type of hardware is missing in the installation kernel, or because of certain functionality included in this kernel, such as ACPI, that can still cause problems on some hardware.

If your system fails to install using the standard Installation mode from the first installation boot screen, try the following:

  1. With the DVD still in the drive, reboot the machine with CtrlAltDel or using the hardware reset button.

  2. When the boot screen appears, press F5, use the arrow keys of your keyboard to navigate to No ACPI and press Enter to launch the boot and installation process. This option disables the support for ACPI power management techniques.

  3. Proceed with the installation as described in Chapter 6, Installation with YaST.

If this fails, proceed as above, but choose Safe Settings instead. This option disables ACPI and DMA support. Most hardware will boot with this option.

If both of these options fail, use the boot options prompt to pass any additional parameters needed to support this type of hardware to the installation kernel. For more information about the parameters available as boot options, refer to the kernel documentation located in /usr/src/linux/Documentation/kernel-parameters.txt.

Tip
Tip: Obtaining Kernel Documentation

Install the kernel-source package to view the kernel documentation.

There are other ACPI-related kernel parameters that can be entered at the boot prompt prior to booting for installation:

acpi=off

This parameter disables the complete ACPI subsystem on your computer. This may be useful if your computer cannot handle ACPI or if you think ACPI in your computer causes trouble.

acpi=force

Always enable ACPI even if your computer has an old BIOS dated before the year 2000. This parameter also enables ACPI if it is set in addition to acpi=off.

acpi=noirq

Do not use ACPI for IRQ routing.

acpi=ht

Run only enough ACPI to enable hyper-threading.

acpi=strict

Be less tolerant of platforms that are not strictly ACPI specification compliant.

pci=noacpi

Disable PCI IRQ routing of the new ACPI system.

pnpacpi=off

This option is for serial or parallel problems when your BIOS setup contains wrong interrupts or ports.

notsc

Disable the time stamp counter. This option can be used to work around timing problems on your systems. It is a recent feature, if you see regressions on your machine, especially time related or even total hangs, this option is worth a try.

nohz=off

Disable the nohz feature. If your machine hangs, this option may help. Otherwise it is of no use.

Once you have determined the right parameter combination, YaST automatically writes them to the boot loader configuration to make sure that the system boots properly next time.

If unexplainable errors occur when the kernel is loaded or during the installation, select Memory Test in the boot menu to check the memory. If Memory Test returns an error, it is usually a hardware error.

40.2.5 Fails to Launch Graphical Installer

After you insert the medium into your drive and reboot your machine, the installation screen comes up, but after you select Installation, the graphical installer does not start.

There are several ways to deal with this situation:

  • Try to select another screen resolution for the installation dialogs.

  • Select Text Mode for installation.

  • Do a remote installation via VNC using the graphical installer.

Procedure 40.3: Change Screen Resolution for Installation
  1. Boot for installation.

  2. Press F3 to open a menu from which to select a lower resolution for installation purposes.

  3. Select Installation and proceed with the installation as described in Chapter 6, Installation with YaST.

Procedure 40.4: Installation in Text Mode
  1. Boot for installation.

  2. Press F3 and select Text Mode.

  3. Select Installation and proceed with the installation as described in Chapter 6, Installation with YaST.

Procedure 40.5: VNC Installation
  1. Boot for installation.

  2. Enter the following text at the boot options prompt:

    vnc=1 vncpassword=SOME_PASSWORD

    Replace SOME_PASSWORD with the password to use for VNC installation.

  3. Select Installation then press Enter to start the installation.

    Instead of starting right into the graphical installation routine, the system continues to run in a text mode, then halts, displaying a message containing the IP address and port number at which the installer can be reached via a browser interface or a VNC viewer application.

  4. If using a browser to access the installer, launch the browser and enter the address information provided by the installation routines on the future SUSE Linux Enterprise Server machine and press Enter:

    http://IP_ADDRESS_OF_MACHINE:5801

    A dialog opens in the browser window prompting you for the VNC password. Enter it and proceed with the installation as described in Chapter 6, Installation with YaST.

    Important
    Important: Cross-platform Support

    Installation via VNC works with any browser under any operating system, provided Java support is enabled.

    Provide the IP address and password to your VNC viewer when prompted. A window opens, displaying the installation dialogs. Proceed with the installation as usual.

40.2.6 Only Minimalistic Boot Screen Started

You inserted the medium into the drive, the BIOS routines are finished, but the system does not start with the graphical boot screen. Instead it launches a very minimalistic text-based interface. This may happen on any machine not providing sufficient graphics memory for rendering a graphical boot screen.

Although the text boot screen looks minimalistic, it provides nearly the same functionality as the graphical one:

Boot Options

Unlike the graphical interface, the different boot options cannot be selected using the cursor keys of your keyboard. The boot menu of the text mode boot screen offers some keywords to enter at the boot prompt. These keywords map to the options offered in the graphical version. Enter your choice and press Enter to launch the boot process.

Custom Boot Options

After selecting a boot option, enter the appropriate keyword at the boot prompt or enter some custom boot options as described in Section 40.2.4, “Fails to Boot”. To launch the installation process, press Enter.

Screen Resolutions

Use the function keys (F1 ... F12) to determine the screen resolution for installation. If you need to boot in text mode, choose F3.

40.2.7 Log Files

For more information about log files that are created during installation, see Section 39.5, “Gathering Information during the Installation”.

40.3 Boot Problems

Boot problems are situations when your system does not boot properly (does not boot to the expected target and login screen).

40.3.1 The GRUB 2 Boot Loader Fails to Load

If the hardware is functioning properly, it is possible that the boot loader is corrupted and Linux cannot start on the machine. In this case, it is necessary to repair the boot loader. To do so, you need to start the Rescue System as described in Section 40.6.2, “Using the Rescue System” and follow the instructions in Section 40.6.2.4, “Modifying and Re-installing the Boot Loader”.

Alternatively, you can use the Rescue System to fix the boot loader as follows. Boot your machine from the installation media. In the boot screen, choose More › Boot Linux System. Select the disk containing the installed system and kernel with the default kernel options.

When the system is booted, start YaST and switch to System › Boot Loader. Make sure that the Write generic Boot Code to MRB option is enabled, and press OK. This fixes the corrupted boot loader by overwriting it, or installs the boot loader if it is missing.

Other reasons for the machine not booting may be BIOS-related:

BIOS Settings

Check your BIOS for references to your hard disk. GRUB 2 may simply not be started if the hard disk itself cannot be found with the current BIOS settings.

BIOS Boot Order

Check whether your system's boot order includes the hard disk. If the hard disk option was not enabled, your system may install properly, but fails to boot when access to the hard disk is required.

40.3.2 No Graphical Login

If the machine starts, but does not boot into the graphical login manager, anticipate problems either with the choice of the default systemd target or the configuration of the X Window System. To check the current systemd default target run the command sudo systemctl get-default. If the value returned is not graphical.target, run the command sudo systemctl isolate graphical.target. If the graphical login screen starts, log in and start YaST › System › Services Manager and set the Default System Target to Graphical Interface. From now on the system should boot into the graphical login screen.

If the graphical login screen does not start even if having booted or switched to the graphical target, your desktop or X Window software is probably misconfigured or corrupted. Examine the log files at /var/log/Xorg.*.log for detailed messages from the X server as it attempted to start. If the desktop fails during start, it may log error messages to the system journal that can be queried with the command journalctl (see Chapter 15, journalctl: Query the systemd Journal for more information). If these error messages hint at a configuration problem in the X server, try to fix these issues. If the graphical system still does not come up, consider reinstalling the graphical desktop.

40.3.3 Root Btrfs Partition Cannot Be Mounted

If a btrfs root partition becomes corrupted, try the following options:

  • Mount the partition with the -o recovery option.

  • If that fails, run btrfs-zero-log on your root partition.

40.3.4 Force Checking Root Partitions

If the root partition becomes corrupted, use the parameter forcefsck on the boot prompt. This passes the option -f (force) to the fsck command.

40.4 Login Problems

Login problems occur when your machine does boot to the expected welcome screen or login prompt, but refuses to accept the user name and password, or accepts them but then does not behave properly (fails to start the graphic desktop, produces errors, drops to a command line, etc.).

40.4.1 Valid User Name and Password Combinations Fail

This usually occurs when the system is configured to use network authentication or directory services and, for some reason, cannot retrieve results from its configured servers. The root user, as the only local user, is the only user that can still log in to these machines. The following are some common reasons a machine appears functional but cannot process logins correctly:

  • The network is not working. For further directions on this, turn to Section 40.5, “Network Problems”.

  • DNS is not working at the moment (which prevents GNOME from working and the system from making validated requests to secure servers). One indication that this is the case is that the machine takes an extremely long time to respond to any action. Find more information about this topic in Section 40.5, “Network Problems”.

  • If the system is configured to use Kerberos, the system's local time may have drifted past the accepted variance with the Kerberos server time (this is typically 300 seconds). If NTP (network time protocol) is not working properly or local NTP servers are not working, Kerberos authentication ceases to function because it depends on common clock synchronization across the network.

  • The system's authentication configuration is misconfigured. Check the PAM configuration files involved for any typographical errors or misordering of directives. For additional background information about PAM and the syntax of the configuration files involved, refer to Chapter 2, Authentication with PAM.

  • The home partition is encrypted. Find more information about this topic in Section 40.4.3, “Login to Encrypted Home Partition Fails”.

In all cases that do not involve external network problems, the solution is to reboot the system into single-user mode and repair the configuration before booting again into operating mode and attempting to log in again. To boot into single-user mode:

  1. Reboot the system. The boot screen appears, offering a prompt.

  2. Press Esc to exit the splash screen and get to the GRUB 2 text-based menu.

  3. Press B to enter the GRUB 2 editor.

  4. Add the following parameter to the line containing the kernel parameters:

    systemd.unit=rescue.target
  5. Press F10.

  6. Enter the user name and password for root.

  7. Make all the necessary changes.

  8. Boot into the full multiuser and network mode by entering systemctl isolate graphical.target at the command line.

40.4.2 Valid User Name and Password Not Accepted

This is by far the most common problem users encounter, because there are many reasons this can occur. Depending on whether you use local user management and authentication or network authentication, login failures occur for different reasons.

Local user management can fail for the following reasons:

  • The user may have entered the wrong password.

  • The user's home directory containing the desktop configuration files is corrupted or write protected.

  • There may be problems with the X Window System authenticating this particular user, especially if the user's home directory has been used with another Linux distribution prior to installing the current one.

To locate the reason for a local login failure, proceed as follows:

  1. Check whether the user remembered his password correctly before you start debugging the whole authentication mechanism. If the user may not remember his password correctly, use the YaST User Management module to change the user's password. Pay attention to the Caps Lock key and unlock it, if necessary.

  2. Log in as root and check the system journal with journalctl -e for error messages of the login process and of PAM.

  3. Try to log in from a console (using CtrlAltF1). If this is successful, the blame cannot be put on PAM, because it is possible to authenticate this user on this machine. Try to locate any problems with the X Window System or the GNOME desktop. For more information, refer to Section 40.4.4, “Login Successful but GNOME Desktop Fails”.

  4. If the user's home directory has been used with another Linux distribution, remove the Xauthority file in the user's home. Use a console login via CtrlAltF1 and run rm .Xauthority as this user. This should eliminate X authentication problems for this user. Try graphical login again.

  5. If the desktop could not start because of corrupt configuration files, proceed with Section 40.4.4, “Login Successful but GNOME Desktop Fails”.

In the following, common reasons a network authentication for a particular user may fail on a specific machine are listed:

  • The user may have entered the wrong password.

  • The user name exists in the machine's local authentication files and is also provided by a network authentication system, causing conflicts.

  • The home directory exists but is corrupt or unavailable. Perhaps it is write protected or is on a server that is inaccessible at the moment.

  • The user does not have permission to log in to that particular host in the authentication system.

  • The machine has changed host names, for whatever reason, and the user does not have permission to log in to that host.

  • The machine cannot reach the authentication server or directory server that contains that user's information.

  • There may be problems with the X Window System authenticating this particular user, especially if the user's home has been used with another Linux distribution prior to installing the current one.

To locate the cause of the login failures with network authentication, proceed as follows:

  1. Check whether the user remembered their password correctly before you start debugging the whole authentication mechanism.

  2. Determine the directory server which the machine relies on for authentication and make sure that it is up and running and properly communicating with the other machines.

  3. Determine that the user's user name and password work on other machines to make sure that his authentication data exists and is properly distributed.

  4. See if another user can log in to the misbehaving machine. If another user can log in without difficulty or if root can log in, log in and examine the system journal with journalctl -e> file. Locate the time stamps that correspond to the login attempts and determine if PAM has produced any error messages.

  5. Try to log in from a console (using CtrlAltF1). If this is successful, the problem is not with PAM or the directory server on which the user's home is hosted, because it is possible to authenticate this user on this machine. Try to locate any problems with the X Window System or the GNOME desktop. For more information, refer to Section 40.4.4, “Login Successful but GNOME Desktop Fails”.

  6. If the user's home directory has been used with another Linux distribution, remove the Xauthority file in the user's home. Use a console login via CtrlAltF1 and run rm .Xauthority as this user. This should eliminate X authentication problems for this user. Try graphical login again.

  7. If the desktop could not start because of corrupt configuration files, proceed with Section 40.4.4, “Login Successful but GNOME Desktop Fails”.

40.4.3 Login to Encrypted Home Partition Fails

It is recommended to use an encrypted home partition for laptops. If you cannot log in to your laptop, the reason is usually simple: your partition could not be unlocked.

During the boot time, you need to enter the passphrase to unlock your encrypted partition. If you do not enter it, the boot process continues, leaving the partition locked.

To unlock your encrypted partition, proceed as follows:

  1. Switch to the text console with CtrlAltF1.

  2. Become root.

  3. Restart the unlocking process again with:

    systemctl restart home.mount
  4. Enter your passphrase to unlock your encrypted partition.

  5. Exit the text console and switch back to the login screen with AltF7.

  6. Log in as usual.

40.4.4 Login Successful but GNOME Desktop Fails

If this is the case, it is likely that your GNOME configuration files have become corrupted. Some symptoms may include the keyboard failing to work, the screen geometry becoming distorted, or even the screen coming up as a bare gray field. The important distinction is that if another user logs in, the machine works normally. It is then likely that the problem can be fixed relatively quickly by simply moving the user's GNOME configuration directory to a new location, which causes GNOME to initialize a new one. Although the user is forced to reconfigure GNOME, no data is lost.

  1. Switch to a text console by pressing CtrlAltF1.

  2. Log in with your user name.

  3. Move the user's GNOME configuration directories to a temporary location:

    mv .gconf  .gconf-ORIG-RECOVER
    mv .gnome2 .gnome2-ORIG-RECOVER
  4. Log out.

  5. Log in again, but do not run any applications.

  6. Recover your individual application configuration data (including the Evolution e-mail client data) by copying the ~/.gconf-ORIG-RECOVER/apps/ directory back into the new ~/.gconf directory as follows:

    cp -a .gconf-ORIG-RECOVER/apps .gconf/

    If this causes the login problems, attempt to recover only the critical application data and reconfigure the remainder of the applications.

40.5 Network Problems

Many problems of your system may be network-related, even though they do not seem to be at first. For example, the reason for a system not allowing users to log in may be a network problem of some kind. This section introduces a simple checklist you can apply to identify the cause of any network problem encountered.

Procedure 40.6: How to Identify Network Problems

When checking the network connection of your machine, proceed as follows:

  1. If you use an Ethernet connection, check the hardware first. Make sure that your network cable is properly plugged into your computer and router (or hub, etc.). The control lights next to your Ethernet connector are normally both be active.

    If the connection fails, check whether your network cable works with another machine. If it does, your network card causes the failure. If hubs or switches are included in your network setup, they may be faulty, as well.

  2. If using a wireless connection, check whether the wireless link can be established by other machines. If not, contact the wireless network's administrator.

  3. Once you have checked your basic network connectivity, try to find out which service is not responding. Gather the address information of all network servers needed in your setup. Either look them up in the appropriate YaST module or ask your system administrator. The following list gives some typical network servers involved in a setup together with the symptoms of an outage.

    DNS (Name Service)

    A broken or malfunctioning name service affects the network's functionality in many ways. If the local machine relies on any network servers for authentication and these servers cannot be found because of name resolution issues, users would not even be able to log in. Machines in the network managed by a broken name server would not be able to see each other and communicate.

    NTP (Time Service)

    A malfunctioning or completely broken NTP service could affect Kerberos authentication and X server functionality.

    NFS (File Service)

    If any application needs data stored in an NFS mounted directory, it cannot start or function properly if this service was down or misconfigured. In the worst case scenario, a user's personal desktop configuration would not come up if their home directory containing the .gconf subdirectory could not be found because of a faulty NFS server.

    Samba (File Service)

    If any application needs data stored in a directory on a faulty Samba server, it cannot start or function properly.

    NIS (User Management)

    If your SUSE Linux Enterprise Server system relies on a faulty NIS server to provide the user data, users cannot log in to this machine.

    LDAP (User Management)

    If your SUSE Linux Enterprise Server system relies on a faulty LDAP server to provide the user data, users cannot log in to this machine.

    Kerberos (Authentication)

    Authentication will not work and login to any machine fails.

    CUPS (Network Printing)

    Users cannot print.

  4. Check whether the network servers are running and whether your network setup allows you to establish a connection:

    Important
    Important: Limitations

    The debugging procedure described below only applies to a simple network server/client setup that does not involve any internal routing. It assumes both server and client are members of the same subnet without the need for additional routing.

    1. Use ping IP_ADDRESS/HOSTNAME (replace with the host name or IP address of the server) to check whether each one of them is up and responding to the network. If this command is successful, it tells you that the host you were looking for is up and running and that the name service for your network is configured correctly.

      If ping fails with destination host unreachable, either your system or the desired server is not properly configured or down. Check whether your system is reachable by running ping IP address or YOUR_HOSTNAME from another machine. If you can reach your machine from another machine, it is the server that is not running or not configured correctly.

      If ping fails with unknown host, the name service is not configured correctly or the host name used was incorrect. For further checks on this matter, refer to Step 4.b. If ping still fails, either your network card is not configured correctly or your network hardware is faulty.

    2. Use host HOSTNAME to check whether the host name of the server you are trying to connect to is properly translated into an IP address and vice versa. If this command returns the IP address of this host, the name service is up and running. If the host command fails, check all network configuration files relating to name and address resolution on your host:

      /etc/resolv.conf

      This file is used to keep track of the name server and domain you are currently using. It can be modified manually or automatically adjusted by YaST or DHCP. Automatic adjustment is preferable. However, make sure that this file has the following structure and all network addresses and domain names are correct:

      search FULLY_QUALIFIED_DOMAIN_NAME
      nameserver IPADDRESS_OF_NAMESERVER

      This file can contain more than one name server address, but at least one of them must be correct to provide name resolution to your host. If needed, adjust this file using the YaST Network Settings module (Hostname/DNS tab).

      If your network connection is handled via DHCP, enable DHCP to change host name and name service information by selecting Set Hostname via DHCP (can be set globally for any interface or per interface) and Update Name Servers and Search List via DHCP in the YaST Network Settings module (Hostname/DNS tab).

      /etc/nsswitch.conf

      This file tells Linux where to look for name service information. It should look like this:

       ...
      hosts: files dns
      networks: files dns
      ...

      The dns entry is vital. It tells Linux to use an external name server. Normally, these entries are automatically managed by YaST, but it would be prudent to check.

      If all the relevant entries on the host are correct, let your system administrator check the DNS server configuration for the correct zone information. For detailed information about DNS, refer to Chapter 25, The Domain Name System. If you have made sure that the DNS configuration of your host and the DNS server are correct, proceed with checking the configuration of your network and network device.

    3. If your system cannot establish a connection to a network server and you have excluded name service problems from the list of possible culprits, check the configuration of your network card.

      Use the command ip addr show NETWORK_DEVICE to check whether this device was properly configured. Make sure that the inet address with the netmask (/MASK) is configured correctly. An error in the IP address or a missing bit in your network mask would render your network configuration unusable. If necessary, perform this check on the server as well.

    4. If the name service and network hardware are properly configured and running, but some external network connections still get long time-outs or fail entirely, use traceroute FULLY_QUALIFIED_DOMAIN_NAME (executed as root) to track the network route these requests are taking. This command lists any gateway (hop) that a request from your machine passes on its way to its destination. It lists the response time of each hop and whether this hop is reachable. Use a combination of traceroute and ping to track down the culprit and let the administrators know.

Once you have identified the cause of your network trouble, you can resolve it yourself (if the problem is located on your machine) or let the system administrators of your network know about your findings so they can reconfigure the services or repair the necessary systems.

40.5.1 NetworkManager Problems

If you have a problem with network connectivity, narrow it down as described in Procedure 40.6, “How to Identify Network Problems”. If NetworkManager seems to be the culprit, proceed as follows to get logs providing hints on why NetworkManager fails:

  1. Open a shell and log in as root.

  2. Restart the NetworkManager:

    systemctl restart Network.Manager
  3. Open a Web page, for example, http://www.opensuse.org as normal user to see, if you can connect.

  4. Collect any information about the state of NetworkManager in /var/log/NetworkManager.

For more information about NetworkManager, refer to Chapter 36, Using NetworkManager.

40.6 Data Problems

Data problems are when the machine may or may not boot properly but, in either case, it is clear that there is data corruption on the system and that the system needs to be recovered. These situations call for a backup of your critical data, enabling you to recover the system state from before your system failed.

40.6.1 Managing Partition Images

Sometimes you need to perform a backup from an entire partition or even hard disk. Linux comes with the dd tool which can create an exact copy of your disk. Combined with gzip you save some space.

Procedure 40.7: Backing up and Restoring Hard Disks
  1. Start a Shell as user root.

  2. Select your source device. Typically this is something like /dev/sda (labeled as SOURCE).

  3. Decide where you want to store your image (labeled as BACKUP_PATH). It must be different from your source device. In other words: if you make a backup from /dev/sda, your image file must not to be stored under /dev/sda.

  4. Run the commands to create a compressed image file:

    dd if=/dev/SOURCE | gzip > /BACKUP_PATH/image.gz
  5. Restore the hard disk with the following commands:

    gzip -dc /BACKUP_PATH/image.gz | dd of=/dev/SOURCE

If you only need to back up a partition, replace the SOURCE placeholder with your respective partition. In this case, your image file can lie on the same hard disk, but on a different partition.

40.6.2 Using the Rescue System

  • Filename: system_repair.xml
  • ID: sec.trouble.data.recover.rescue

There are several reasons a system could fail to come up and run properly. A corrupted file system following a system crash, corrupted configuration files, or a corrupted boot loader configuration are the most common ones.

To help you to resolve these situations, SUSE Linux Enterprise Server contains a rescue system that you can boot. The rescue system is a small Linux system that can be loaded into a RAM disk and mounted as root file system, allowing you to access your Linux partitions from the outside. Using the rescue system, you can recover or modify any important aspect of your system.

  • Manipulate any type of configuration file.

  • Check the file system for defects and start automatic repair processes.

  • Access the installed system in a change root environment.

  • Check, modify, and re-install the boot loader configuration.

  • Recover from a badly installed device driver or unusable kernel.

  • Resize partitions using the parted command. Find more information about this tool at the GNU Parted Web site http://www.gnu.org/software/parted/parted.html.

The rescue system can be loaded from various sources and locations. The simplest option is to boot the rescue system from the original installation medium.

Note
Note: IBM z Systems Starting the Rescue System

On IBM z Systems the installation system can be used for rescue purposes. To start the rescue system follow the instructions in Section 40.7, “IBM z Systems: Using initrd as a Rescue System”.

  1. Insert the installation medium into your DVD drive.

  2. Reboot the system.

  3. At the boot screen, press F4 and choose DVD-ROM. Then choose Rescue System from the main menu.

  4. Enter root at the Rescue: prompt. A password is not required.

If your hardware setup does not include a DVD drive, you can boot the rescue system from a network source. The following example applies to a remote boot scenario—if using another boot medium, such as a DVD, modify the info file accordingly and boot as you would for a normal installation.

  1. Enter the configuration of your PXE boot setup and add the lines install=PROTOCOL://INSTSOURCE and rescue=1. If you need to start the repair system, use repair=1 instead. As with a normal installation, PROTOCOL stands for any of the supported network protocols (NFS, HTTP, FTP, etc.) and INSTSOURCE for the path to your network installation source.

  2. Boot the system using Wake on LAN, as described in Section 9.7, “Wake on LAN”.

  3. Enter root at the Rescue: prompt. A password is not required.

Once you have entered the rescue system, you can use the virtual consoles that can be reached with AltF1 to AltF6.

A shell and other useful utilities, such as the mount program, are available in the /bin directory. The /sbin directory contains important file and network utilities for reviewing and repairing the file system. This directory also contains the most important binaries for system maintenance, such as fdisk, mkfs, mkswap, mount, and shutdown, ip and ss for maintaining the network. The directory /usr/bin contains the vi editor, find, less, and SSH.

To see the system messages, either use the command dmesg or view the system log with journalctl.

40.6.2.1 Checking and Manipulating Configuration Files

As an example for a configuration that might be fixed using the rescue system, imagine you have a broken configuration file that prevents the system from booting properly. You can fix this using the rescue system.

To manipulate a configuration file, proceed as follows:

  1. Start the rescue system using one of the methods described above.

  2. To mount a root file system located under /dev/sda6 to the rescue system, use the following command:

    mount /dev/sda6 /mnt

    All directories of the system are now located under /mnt

  3. Change the directory to the mounted root file system:

    cd /mnt
  4. Open the problematic configuration file in the vi editor. Adjust and save the configuration.

  5. Unmount the root file system from the rescue system:

    umount /mnt
  6. Reboot the machine.

40.6.2.2 Repairing and Checking File Systems

Generally, file systems cannot be repaired on a running system. If you encounter serious problems, you may not even be able to mount your root file system and the system boot may end with a kernel panic. In this case, the only way is to repair the system from the outside. The system contains the utilities to check and repair the btrfs, ext2, ext3, ext4, reiserfs, xfs, dosfs, and vfat file systems. Look for the command fsck. FILESYSTEM, for example, if you need a file system check for btrfs, use fsck.btrfs.

40.6.2.3 Accessing the Installed System

If you need to access the installed system from the rescue system, you need to do this in a change root environment. For example, to modify the boot loader configuration, or to execute a hardware configuration utility.

To set up a change root environment based on the installed system, proceed as follows:

  1. Tip
    Tip: Import LVM Volume Groups

    If you are using a LVM setup (refer to Part II, “Logical Volumes (LVM)” for more general details), import all existing volume groups in order to be able to find and mount the device(s):

    rootvgimport -a

    Run lsblk to check which node corresponds to the root partition. It is /dev/sda2 in our example:

    lsblk
    NAME        MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINT
    sda           8:0    0 149,1G  0 disk
    ├─sda1        8:1    0     2G  0 part  [SWAP]
    ├─sda2        8:2    0    20G  0 part  /
    └─sda3        8:3    0   127G  0 part
      └─cr_home 254:0    0   127G  0 crypt /home
  2. Mount the root partition from the installed system:

    mount /dev/sda2 /mnt
  3. Mount /proc, /dev, and /sys partitions:

    mount -t proc none /mnt/proc
    mount --rbind /dev /mnt/dev
    mount --rbind /sys /mnt/sys
  4. Now you can change root into the new environment, keeping the bash shell:

    chroot /mnt /bin/bash
  5. Finally, mount the remaining partitions from the installed system:

    mount -a
  6. Now you have access to the installed system. Before rebooting the system, unmount the partitions with umount -a and leave the change root environment with exit.

Warning
Warning: Limitations

Although you have full access to the files and applications of the installed system, there are some limitations. The kernel that is running is the one that was booted with the rescue system, not with the change root environment. It only supports essential hardware and it is not possible to add kernel modules from the installed system unless the kernel versions are identical. Always check the version of the currently running (rescue) kernel with uname -r and then find out if a matching subdirectory exists in the /lib/modules directory in the change root environment. If yes, you can use the installed modules, otherwise you need to supply their correct versions on other media, such as a flash disk. Most often the rescue kernel version differs from the installed one — then you cannot simply access a sound card, for example. It is also not possible to start a graphical user interface.

Also note that you leave the change root environment when you switch the console with AltF1 to AltF6.

40.6.2.4 Modifying and Re-installing the Boot Loader

Sometimes a system cannot boot because the boot loader configuration is corrupted. The start-up routines cannot, for example, translate physical drives to the actual locations in the Linux file system without a working boot loader.

To check the boot loader configuration and re-install the boot loader, proceed as follows:

  1. Perform the necessary steps to access the installed system as described in Section 40.6.2.3, “Accessing the Installed System”.

  2. Check that the GRUB 2 boot loader is installed on the system. If not, install the package grub2 and run

    grub2-install /dev/sda
  3. Check whether the following files are correctly configured according to the GRUB 2 configuration principles outlined in Chapter 12, The Boot Loader GRUB 2 and apply fixes if necessary.

    • /etc/default/grub

    • /boot/grub2/device.map (optional file, only present if created manually)

    • /boot/grub2/grub.cfg (this file is generated, do not edit)

    • /etc/sysconfig/bootloader

  4. Re-install the boot loader using the following command sequence:

    grub2-mkconfig -o /boot/grub2/grub.cfg
  5. Unmount the partitions, log out from the change root environment, and reboot the system:

    umount -a
    exit
    reboot

40.6.2.5 Fixing Kernel Installation

A kernel update may introduce a new bug which can impact the operation of your system. For example a driver for a piece of hardware in your system may be faulty, which prevents you from accessing and using it. In this case, revert to the last working kernel (if available on the system) or install the original kernel from the installation media.

Tip
Tip: How to Keep Last Kernels after Update

To prevent failures to boot after a faulty kernel update, use the kernel multiversion feature and tell libzypp which kernels you want to keep after the update.

For example to always keep the last two kernels and the currently running one, add

multiversion.kernels = latest,latest-1,running

to the /etc/zypp/zypp.conf file. See Chapter 15, Installing Multiple Kernel Versions for more information.

A similar case is when you need to re-install or update a broken driver for a device not supported by SUSE Linux Enterprise Server. For example when a hardware vendor uses a specific device, such as a hardware RAID controller, which needs a binary driver to be recognized by the operating system. The vendor typically releases a Driver Update Disk (DUD) with the fixed or updated version of the required driver.

In both cases you need to access the installed system in the rescue mode and fix the kernel related problem, otherwise the system may fail to boot correctly:

  1. Boot from the SUSE Linux Enterprise Server installation media.

  2. If you are recovering after a faulty kernel update, skip this step. If you need to use a driver update disk (DUD), press F6 to load the driver update after the boot menu appears, and choose the path or URL to the driver update and confirm with Yes.

  3. Choose Rescue System from the boot menu and press Enter. If you chose to use DUD, you will be asked to specify where the driver update is stored.

  4. Enter root at the Rescue: prompt. A password is not required.

  5. Manually mount the target system and change root into the new environment. For more information, see Section 40.6.2.3, “Accessing the Installed System”.

  6. If using DUD, install/re-install/update the faulty device driver package. Always make sure the installed kernel version exactly matches the version of the driver you are installing.

    If fixing faulty kernel update installation, you can install the original kernel from the installation media with the following procedure.

    1. Identify your DVD device with hwinfo --cdrom and mount it with mount /dev/sr0 /mnt.

    2. Navigate to the directory where your kernel files are stored on the DVD, for example cd /mnt/suse/x86_64/.

    3. Install required kernel-*, kernel-*-base, and kernel-*-extra packages of your flavor with the rpm -i command.

  7. Update configuration files and reinitialize the boot loader if needed. For more information, see Section 40.6.2.4, “Modifying and Re-installing the Boot Loader”.

  8. Remove any bootable media from the system drive and reboot.

40.7 IBM z Systems: Using initrd as a Rescue System

  • Filename: zseries_rescue_initrd.xml
  • ID: sec.zseries.rescue

If the kernel of the SUSE® Linux Enterprise Server for IBM z Systems is upgraded or modified, it is possible to reboot the system accidentally in an inconsistent state, so standard procedures of IPLing the installed system fail. In such a case, you may use the installation system for rescue purposes.

IPL the SUSE Linux Enterprise Server for IBM z Systems installation system as described in Section 4.2, “Preparing for Installation”. Choose Start Installation and enter all required parameters. After the installation system has loaded and you are asked which display type to use to control the installation, select SSH. Now you can log in to the system with SSH as root without a password.

In this state, no disks are configured. You need to configure them before you can proceed.

Procedure 40.8: Configuring DASDs
  1. Configure DASDs with the following command:

    dasd_configure 0.0.0150 1 0

    0.0.0150 is the channel to which the DASD is connected. The 1 means activate the disk (a 0 at this place would deactivate the disk). The 0 stands for no DIAG mode for the disk (a 1 here would enable DAIG access to the disk).

  2. Now the DASD is online (check with cat /proc/partitions) and can used for subsequent commands.

Procedure 40.9: Configuring a zFCP Disk
  1. To configure a zFCP disk, it is necessary to first configure the zFCP adapter. Do this with the following command:

    zfcp_host_configure 0.0.4000 1

    0.0.4000 is the channel to which the adapter is attached and 1 stands for activate (a 0 here would deactivate the adapter).

  2. After the adapter is activated, a disk can be configured. Do this with the following command:

    zfcp_disk_configure 0.0.4000 1234567887654321 8765432100000000  1

    0.0.4000 is the previously-used channel ID, 1234567887654321 is the WWPN (World wide Port Number), and 8765432100000000 is the LUN (logical unit number). The 1 stands for activating the disk (a 0 here would deactivate the disk).

  3. Now the zFCP disk is online (check with cat /proc/partitions) and can used for subsequent commands.

Now the rescue system is fully set up and you can start repairing the installed system. See Section 40.6.2, “Using the Rescue System” for instructions on how to repair the most common issues.

A Documentation Updates

  • Filename: admin_docupdates.xml
  • ID: app.admin.docupdates

This chapter lists content changes for this document.

This manual was updated on the following dates:

A.2 December 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)

General

A.3 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)

General
Chapter 4, YaST
Chapter 5, YaST in Text Mode
Chapter 6, Managing Software with Command Line Tools
Chapter 7, System Recovery and Snapshot Management with Snapper
Chapter 8, Remote Access with VNC
Chapter 9, File Copying with RSync
  • Completely revised former File Synchronization chapter and focused on Rsync.

Chapter 13, The systemd Daemon
Chapter 16, Basic Networking
Chapter 21, Dynamic Kernel Device Management with udev
  • Fixed udevadm commands.

Chapter 22, Live Patching the Linux Kernel Using kGraft

Updated Section 22.4, “Patch Lifecycle” (Fate #322212).

Chapter 23, Special System Features
Part II, “Booting a Linux System”
  • Reordered included chapters so that they follow the boot process order.

Chapter 33, The Proxy Server Squid
  • Explained the YaST Squid module.

Bugfixes

A.4 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)

General
  • The e-mail address for documentation feedback has changed to doc-team@suse.com.

  • The documentation for Docker has been enhanced and renamed to Docker Guide.

Chapter 3, YaST Online Update
Chapter 6, Managing Software with Command Line Tools
  • zypper patch no longer installs optional patches by default. To install optional patches, use the --with-optional parameter (FATE#320447).

Chapter 7, System Recovery and Snapshot Management with Snapper
Chapter 10, Introduction to the Booting Process
  • Advised users to repair file system in case root file system fails on boot time (FATE#320443).

Chapter 12, The Boot Loader GRUB 2
Chapter 16, Basic Networking
Chapter 24, Time Synchronization with NTP
  • Added information on the Synchronize without Daemon start-up option. Chroot jail is no longer the default (FATE #320392).

Note: NFSv2
Chapter 33, The Proxy Server Squid
  • Updated chapter for Squid 3.5 (FATE#319674).

Section 39.5, “Gathering Information during the Installation”
  • Added section about log files created during installation (FATE#320015).

Bugfixes

A.5 March 2016 (Maintenance Release of SUSE Linux Enterprise Server 12 SP1)

Chapter 10, Introduction to the Booting Process

Added a note about initramfs migration from swap to LVM (https://bugzilla.suse.com/show_bug.cgi?id=).

A.6 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)

General
  • SMT Guide is now part of the documentation for SUSE Linux Enterprise Server.

  • Add-ons provided by SUSE have been renamed as modules and extensions. The manuals have been updated to reflect this change.

  • Numerous small fixes and additions to the documentation, based on technical feedback.

  • The registration service has been changed from Novell Customer Center to SUSE Customer Center.

  • In YaST, you will now reach Network Settings via the System group. Network Devices is gone (https://bugzilla.suse.com/show_bug.cgi?id=867809).

Chapter 7, System Recovery and Snapshot Management with Snapper
Chapter 8, Remote Access with VNC
Chapter 6, Managing Software with Command Line Tools
Chapter 15, journalctl: Query the systemd Journal
Chapter 12, The Boot Loader GRUB 2
  • Updated/simplified the whole chapter to match the latest GRUB version, both command line and YaST version.

Chapter 11, UEFI (Unified Extensible Firmware Interface)
Chapter 16, Basic Networking
Chapter 25, The Domain Name System
Chapter 27, Sharing File Systems with NFS
Available Data Synchronization Software
  • Mentioned cloud computing for file synchronization.

Chapter 31, The Apache HTTP Server
Chapter 40, Common Problems and Their Solutions
Part III, “System”
Bugfixes

A.7 February 2015 (Documentation Maintenance Update)

A.8 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)

General
  • Removed all KDE documentation and references because KDE is no longer shipped.

  • Removed all references to SuSEconfig, which is no longer supported (Fate #100011).

  • Move from System V init to systemd (Fate #310421). Updated affected parts of the documentation.

  • YaST Runlevel Editor has changed to Services Manager (Fate #312568). Updated affected parts of the documentation.

  • Removed all references to ISDN support, as ISDN support has been removed (Fate #314594).

  • Removed all references to the YaST DSL module as it is no longer shipped (Fate #316264).

  • Removed all references to the YaST Modem module as it is no longer shipped (Fate #316264).

  • Btrfs has become the default file system for the root partition (Fate #315901). Updated affected parts of the documentation.

  • The dmesg now provides human-readable time stamps in ctime()-like format (Fate #316056). Updated affected parts of the documentation.

  • syslog and syslog-ng have been replaced by rsyslog (Fate #316175). Updated affected parts of the documentation.

  • MariaDB is now shipped as the relational database instead of MySQL (Fate #313595). Updated affected parts of the documentation.

  • SUSE-related products are no longer available from http://download.novell.com but from http://download.suse.com. Adjusted links accordingly.

  • Novell Customer Center has been replaced with SUSE Customer Center. Updated affected parts of the documentation.

  • /var/run is mounted as tmpfs (Fate #303793). Updated affected parts of the documentation.

  • The following architectures are no longer supported: IA64 and x86. Updated affected parts of the documentation.

  • The traditional method for setting up the network with ifconfig has been replaced by wicked. Updated affected parts of the documentation.

  • A lot of networking commands are deprecated and have been replaced by newer commands (usually ip). Updated affected parts of the documentation.

    arp: ip neighbor
    ifconfig: ip addr, ip link
    iptunnel: ip tunnel
    iwconfig: iw
    nameif: ip link, ifrename
    netstat: ss, ip route, ip -s link, ip maddr
    route: ip route
  • Numerous small fixes and additions to the documentation, based on technical feedback.

Chapter 3, YaST Online Update
  • YaST provides an option to enable or disable the use of delta RPMs (Fate #314867).

  • Before installing patches that require a reboot, you are notified by YaST and can choose how to proceed.

Chapter 39, Gathering System Information for Support
Chapter 5, YaST in Text Mode
  • Added information on how to filter and select packages in the software installation module.

Chapter 6, Managing Software with Command Line Tools
Chapter 7, System Recovery and Snapshot Management with Snapper
Chapter 8, Remote Access with VNC
  • The default VNC viewer is now tigervnc.

  • Added corrections on window manager start-up in persistent VNC sessions.

Chapter 10, Introduction to the Booting Process
  • Significantly shortened the chapter, because System V init has been replaced by systemd. systemd is now described in a separate chapter: Chapter 13, The systemd Daemon.

Chapter 13, The systemd Daemon
Chapter 15, journalctl: Query the systemd Journal

Added a new chapter (http://bugzilla.suse.com/show_bug.cgi?id=878352).

Chapter 12, The Boot Loader GRUB 2
Chapter 11, UEFI (Unified Extensible Firmware Interface)
  • Updated the chapter and added new features (Fate #314510, Fate #316365).

  • Added instructions on where to find the SUSE Key certificate (Doc Comment #25080).

Chapter 17, Printer Operation

Updated chapter and section according to new CUPS version and with PDF now being a common printing data format (Fate #314630).

Chapter 18, The X Window System
Chapter 16, Basic Networking
Chapter 30, SLP
  • Re-wrote chapter to provide significantly more information on the slptool command.

Chapter 25, The Domain Name System
  • The YaST DNS module now supports configuring forwarders (Fate #309036).

Chapter 26, DHCP
  • Removed dhcpcd as it is no longer shipped (Fate #316111).

Chapter 28, Samba
Chapter 27, Sharing File Systems with NFS
  • Configuring NFSv4 shares is now mostly similar to NFSv3, especially the previously required bind mount setting is now deprecated (Fate #315589).

  • Mounting NFS volumes locally on the exporting server is not supported.

Chapter 29, On-Demand Mounting with Autofs
  • Added a chapter on autofs (Fate #316185).

Chapter 31, The Apache HTTP Server
Chapter 32, Setting Up an FTP Server with YaST
  • pure-ftpd was dropped (Fate #315176, Fate #316308).

Chapter 37, Power Management
  • Removed obsolete references to the pm-utils package.

Chapter 40, Common Problems and Their Solutions
Wi-Fi Configuration
Tablet PCs
  • Removed deprecated chapter about tablet PCs.

Bugfixes

B An Example Network

  • Filename: network_scheme.xml
  • ID: app.nwscheme

This example network is used across all network-related chapters of the SUSE® Linux Enterprise Server documentation.

SUSE Linux Enterprise Server 12 SP3

Deployment Guide

Shows how to install single or multiple systems and how to exploit the product inherent capabilities for a deployment infrastructure. Choose from various approaches, ranging from a local installation or a network installation server to a mass deployment using a remote-controlled, highly-customized, and automated installation technique.

Publication Date: April 04, 2018
About This Guide
Required Background
Available Documentation
Feedback
Documentation Conventions
1 Planning for SUSE Linux Enterprise Server
1.1 Considerations for Deployment of a SUSE Linux Enterprise Server
1.2 Deployment of SUSE Linux Enterprise Server
1.3 Running SUSE Linux Enterprise Server
1.4 Registering SUSE Linux Enterprise Server
I Installation Preparation
2 Installation on AMD64 and Intel 64
2.1 System Requirements for Operating Linux
2.2 Installation Considerations
2.3 Boot and Installation Media
2.4 Installation Procedure
2.5 Controlling the Installation
2.6 Dealing with Boot and Installation Problems
3 Installation on IBM POWER
3.1 Requirements
3.2 Preparation
3.3 For More Information
4 Installation on IBM z Systems
4.1 General Information and Requirements
4.2 Preparing for Installation
4.3 The parmfile—Automating the System Configuration
4.4 Using the vt220 Terminal Emulator
4.5 Further In-Depth Information about IBM z Systems
5 Installation on ARM AArch64
5.1 System Requirements for Operating Linux
5.2 Installation Considerations
5.3 Boot and Installation Media
5.4 Installation Procedure
5.5 Controlling the Installation
5.6 Dealing with Boot and Installation Problems
II The Installation Workflow
6 Installation with YaST
6.1 Choosing the Installation Method
6.2 System Start-up for Installation
6.3 Steps of the Installation
6.4 Installer Self-Update
6.5 Language, Keyboard and License Agreement
6.6 IBM z Systems: Disk Activation
6.7 Network Settings
6.8 SUSE Customer Center Registration
6.9 Extension Selection
6.10 System Role
6.11 Suggested Partitioning
6.12 Clock and Time Zone
6.13 Create New User
6.14 Password for the System Administrator root
6.15 Installation Settings
6.16 Performing the Installation
7 Cloning Disk Images
7.1 Cleaning Up Unique System Identifiers
III Setting Up an Installation Server
8 Setting Up the Server Holding the Installation Sources
8.1 Setting Up an Installation Server Using YaST
8.2 Setting Up an NFS Repository Manually
8.3 Setting Up an FTP Repository Manually
8.4 Setting Up an HTTP Repository Manually
8.5 Managing an SMB Repository
8.6 Using ISO Images of the Installation Media on the Server
9 Preparing the Boot of the Target System
9.1 Setting Up a DHCP Server
9.2 Setting Up a TFTP Server
9.3 Installing Files on TFTP Server
9.4 PXELINUX Configuration Options
9.5 Preparing the Target System for PXE Boot
9.6 Preparing the Target System for Wake on LAN
9.7 Wake on LAN
9.8 Wake on LAN with YaST
9.9 Booting from CD or USB Drive Instead of PXE
IV Remote Installation
10 Remote Installation
10.1 Installation Scenarios for Remote Installation
10.2 Booting the Target System for Installation
10.3 Monitoring the Installation Process
V Initial System Configuration
11 Setting Up Hardware Components with YaST
11.1 Setting Up Your System Keyboard Layout
11.2 Setting Up Sound Cards
11.3 Setting Up a Printer
12 Advanced Disk Setup
12.1 Using the YaST Partitioner
12.2 LVM Configuration
12.3 Soft RAID Configuration with YaST
13 Installing or Removing Software
13.1 Definition of Terms
13.2 Registering Installed System
13.3 Using the YaST Software Manager
13.4 Managing Software Repositories and Services
13.5 Keeping the System Up-to-date
14 Installing Modules, Extensions, and Third Party Add-On Products
14.1 List of Optional Modules
14.2 Installing Modules and Extensions from Online Channels
14.3 Installing Extensions and Third Party Add-On Products from Media
14.4 SUSE Software Development Kit (SDK) 12 SP3
14.5 SUSE Package Hub
15 Installing Multiple Kernel Versions
15.1 Enabling and Configuring Multiversion Support
15.2 Installing/Removing Multiple Kernel Versions with YaST
15.3 Installing/Removing Multiple Kernel Versions with Zypper
16 Managing Users with YaST
16.1 User and Group Administration Dialog
16.2 Managing User Accounts
16.3 Additional Options for User Accounts
16.4 Changing Default Settings for Local Users
16.5 Assigning Users to Groups
16.6 Managing Groups
16.7 Changing the User Authentication Method
17 Changing Language and Country Settings with YaST
17.1 Changing the System Language
17.2 Changing the Country and Time Settings
VI Updating and Upgrading SUSE Linux Enterprise
18 Life Cycle and Support
18.1 Terminology
18.2 Product Life Cycle
18.3 Module Life Cycles
18.4 Generating Periodic Life Cycle Report
18.5 Support Levels
18.6 Repository Model
19 Upgrading SUSE Linux Enterprise
19.1 Supported Upgrade Paths to SLE 12 SP3
19.2 Online and Offline Upgrade
19.3 Preparing the System
19.4 Upgrading on IBM z Systems
19.5 IBM POWER: Starting an X Server
20 Upgrading Offline
20.1 Conceptual Overview
20.2 Starting the Upgrade from Installation Medium
20.3 Starting Upgrade from Network Source
20.4 Starting Upgrade from Hard Disk
20.5 Enabling Automatic Upgrade
20.6 Upgrading SUSE Linux Enterprise
20.7 Updating via SUSE Manager
20.8 Updating Registration Status after Rollback
20.9 Registering Your System
21 Upgrading Online
21.1 Conceptual Overview
21.2 Service Pack Migration Workflow
21.3 Canceling Service Pack Migration
21.4 Upgrading with the Online Migration Tool (YaST)
21.5 Upgrading with Zypper
21.6 Upgrading with Plain Zypper
21.7 Rolling Back a Service Pack
22 Backporting Source Code
22.1 Reasons for Backporting
22.2 Reasons against Backports
22.3 The Implications of Backports for Interpreting Version Numbers
22.4 How to Check Which Bugs are Fixed and Which Features are Backported and Available
A Documentation Updates
A.1 January 2018 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)
A.2 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)
A.3 April 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP2)
A.4 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)
A.5 March 2016 (Maintenance Release of SUSE Linux Enterprise Server 12 SP1)
A.6 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)
A.7 February 2015 (Documentation Maintenance Update)
A.8 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)
B GNU Licenses
B.1 GNU Free Documentation License

Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

About This Guide

  • Filename: deployment_intro.xml
  • ID: preface.deployment

Installations of SUSE Linux Enterprise Server are possible in different ways. It is impossible to cover all combinations of boot, or installation server, automated installations or deploying images. This manual should help with selecting the appropriate method of deployment for your installation.

Part I, “Installation Preparation”

The standard deployment instructions differ depending on the architecture used. For differences and requirements regarding the architecture, see this part.

Part II, “The Installation Workflow”

Most tasks that are needed during installations are described here. This includes the manual setup of your computer and installation of additional software.

Part III, “Setting Up an Installation Server”

SUSE® Linux Enterprise Server can be installed in different ways. Apart from the usual media installation, you can choose from various network-based approaches. This part describes setting up an installation server and how to prepare the boot of the target system for installation.

Part IV, “Remote Installation”

This part introduces the most common installation scenarios for remote installations. While some still require user interaction or some degree of physical access to the target system, others are completely automated and hands-off. Learn which approach is best for your scenario.

Part V, “Initial System Configuration”

Learn how to configure your system after installation. This part covers common tasks like setting up hardware components, installing or removing software, managing users, or changing settings with YaST.

Part VI, “Updating and Upgrading SUSE Linux Enterprise”

This part will give you some background information on terminology, SUSE product lifecycles and Service Pack releases, and recommended upgrade policies.

1 Required Background

  • Filename: common_intro_target_audience_i.xml
  • ID: cha.generic

To keep the scope of these guidelines manageable, certain technical assumptions have been made:

  • You have some computer experience and are familiar with common technical terms.

  • You are familiar with the documentation for your system and the network on which it runs.

  • You have a basic understanding of Linux systems.

2 Available Documentation

  • Filename: common_intro_available_doc_i.xml
  • ID: no ID found
Note
Note: Online Documentation and Latest Updates

Documentation for our products is available at http://www.suse.com/documentation/, where you can also find the latest updates, and browse or download the documentation in various formats.

In addition, the product documentation is usually available in your installed system under /usr/share/doc/manual.

The following documentation is available for this product:

Installation Quick Start

Lists the system requirements and guides you step-by-step through the installation of SUSE Linux Enterprise Server from DVD, or from an ISO image.

Deployment Guide

Shows how to install single or multiple systems and how to exploit the product inherent capabilities for a deployment infrastructure. Choose from various approaches, ranging from a local installation or a network installation server to a mass deployment using a remote-controlled, highly-customized, and automated installation technique.

Administration Guide

Covers system administration tasks like maintaining, monitoring and customizing an initially installed system.

Virtualization Guide

Describes virtualization technology in general, and introduces libvirt—the unified interface to virtualization—and detailed information on specific hypervisors.

Storage Administration Guide

Provides information about how to manage storage devices on a SUSE Linux Enterprise Server.

AutoYaST

AutoYaST is a system for unattended mass deployment SUSE Linux Enterprise Server systems using an AutoYaST profile containing installation and configuration data. The manual guides you through the basic steps of auto-installation: preparation, installation, and configuration.

Security Guide

Introduces basic concepts of system security, covering both local and network security aspects. Shows how to use the product inherent security software like AppArmor or the auditing system that reliably collects information about any security-relevant events.

Security and Hardening Guide

Deals with the particulars of installing and setting up a secure SUSE Linux Enterprise Server, and additional post-installation processes required to further secure and harden that installation. Supports the administrator with security-related choices and decisions.

System Analysis and Tuning Guide

An administrator's guide for problem detection, resolution and optimization. Find how to inspect and optimize your system by means of monitoring tools and how to efficiently manage resources. Also contains an overview of common problems and solutions and of additional help and documentation resources.

SMT Guide

An administrator's guide to Subscription Management Tool—a proxy system for SUSE Customer Center with repository and registration targets. Learn how to install and configure a local SMT server, mirror and manage repositories, manage client machines, and configure clients to use SMT.

GNOME User Guide

Introduces the GNOME desktop of SUSE Linux Enterprise Server. It guides you through using and configuring the desktop and helps you perform key tasks. It is intended mainly for end users who want to make efficient use of GNOME as their default desktop.

3 Feedback

  • Filename: common_intro_feedback_i.xml
  • ID: no ID found

Several feedback channels are available:

Bugs and Enhancement Requests

For services and support options available for your product, refer to http://www.suse.com/support/.

Help for openSUSE is provided by the community. Refer to https://en.opensuse.org/Portal:Support for more information.

To report bugs for a product component, go to https://scc.suse.com/support/requests, log in, and click Create New.

User Comments

We want to hear your comments about and suggestions for this manual and the other documentation included with this product. Use the User Comments feature at the bottom of each page in the online documentation or go to http://www.suse.com/documentation/feedback.html and enter your comments there.

Mail

For feedback on the documentation of this product, you can also send a mail to doc-team@suse.com. Make sure to include the document title, the product version and the publication date of the documentation. To report errors or suggest enhancements, provide a concise description of the problem and refer to the respective section number and page (or URL).

4 Documentation Conventions

  • Filename: common_intro_typografie_i.xml
  • ID: no ID found

The following notices and typographical conventions are used in this documentation:

  • /etc/passwd: directory names and file names

  • PLACEHOLDER: replace PLACEHOLDER with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • package name : name of a package

  • Alt, AltF1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File › Save As: menu items, buttons

  • x86_64 This paragraph is only relevant for the AMD64/Intel 64 architecture. The arrows mark the beginning and the end of the text block.

    System z, POWER This paragraph is only relevant for the architectures z Systems and POWER. The arrows mark the beginning and the end of the text block.

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

  • Commands that must be run with root privileges. Often you can also prefix these commands with the sudo command to run them as non-privileged user.

    root # command
    tux > sudo command
  • Commands that can be run by non-privileged users.

    tux > command
  • Notices

    Warning
    Warning: Warning Notice

    Vital information you must be aware of before proceeding. Warns you about security issues, potential loss of data, damage to hardware, or physical hazards.

    Important
    Important: Important Notice

    Important information you should be aware of before proceeding.

    Note
    Note: Note Notice

    Additional information, for example about differences in software versions.

    Tip
    Tip: Tip Notice

    Helpful information, like a guideline or a piece of practical advice.

1 Planning for SUSE Linux Enterprise Server

  • Filename: planning.xml
  • ID: cha.planning

1.1 Considerations for Deployment of a SUSE Linux Enterprise Server

The implementation of an operating system either in an existing IT environment or as a completely new rollout must be carefully prepared. At the beginning of the planning process, you should try to define the project goals and necessary features. This must always be done individually for each project, but the questions to answer should include the following:

  • How many installations should be done? Depending on this, the best deployment methods differ.

  • Will the system run as physical host or as a virtual machine?

  • Will the system be in a hostile environment? Have a look at Chapter 1, Security and Confidentiality to get an overview of consequences.

  • How will you get regular updates? All patches are provided online for registered users. Find the registration and patch support database at http://download.suse.com/.

  • Do you need help for your local installation? SUSE provides training, support, and consulting for all topics pertaining to SUSE Linux Enterprise Server. Find more information about this at https://www.suse.com/products/server/.

  • Do you need third-party products? Make sure that the required product is also supported on the desired platform. SUSE can provide help to support software on different platforms when needed.

1.2 Deployment of SUSE Linux Enterprise Server

To make sure that your system will run flawlessly, always try to use certified hardware. The hardware certification process is an ongoing process and the database of certified hardware is updated regularly. Find the search form for certified hardware at http://www.suse.com/yessearch/Search.jsp.

Depending on the number of desired installations, it is beneficial to use installation servers or even completely automatic installations. When using Xen or KVM virtualization technologies, network root file systems or network storage solutions like iSCSI should be considered.

SUSE Linux Enterprise Server provides you with a broad variety of services. Find an overview of the documentation in this book in About This Guide. Most of the needed configurations can be made with YaST, the SUSE configuration utility. In addition, many manual configurations are described in the corresponding chapters.

In addition to the plain software installation, you should consider training the end users of the systems and help desk staff.

1.3 Running SUSE Linux Enterprise Server

The SUSE Linux Enterprise Server operating system is a well-tested and stable system. Unfortunately, this does not prevent hardware failures or other causes for downtime or data loss. For any serious computing task where data loss could occur, a regular backup should be done.

For optimal security and data safety, you should make regular updates of all the operated machines. If you have a mission critical server, you should run a second identical (pre-production) machine that you can use to test all changes. This also gives you the possibility of switching machines in the case of hardware failure.

1.4 Registering SUSE Linux Enterprise Server

To get technical support and product updates, you need to register and activate your SUSE product with the SUSE Customer Center. We recommend to register during the installation, since this will enable you to install the system with the latest updates and patches available. However, if you are offline or want to skip the registration step, you can register at any time later from the installed system.

In case your organization does not provide a local registration server, registering SUSE Linux requires a SUSE account. In case you do not have a SUSE account yet, go to the SUSE Customer Center home page (https://scc.suse.com/) to create one.

During the installation you will be asked to enter your registration code. For details, dee Section 6.8, “SUSE Customer Center Registration”.

If you deploy your instances automatically using AutoYaST, you can register the system during the installation by providing the respective information in the AutoYaST control file. For details, see Section 4.3, “System Registration and Extension Selection”

For registering an already installed system, see Section 13.2, “Registering Installed System”.

Part I Installation Preparation

2 Installation on AMD64 and Intel 64

This chapter describes the steps necessary to prepare for the installation of SUSE Linux Enterprise Server on AMD64 and Intel 64 computers. It introduces the steps required to prepare for various installation methods. The list of hardware requirements provides an overview of systems supported by SUSE Linux Enterprise Server. Find information about available installation methods and several common known problems. Also learn how to control the installation, provide installation media, and boot with regular methods.

3 Installation on IBM POWER

This chapter describes the procedure for preparing the installation of SUSE® Linux Enterprise Server on IBM POWER systems.

4 Installation on IBM z Systems

This chapter describes the procedure for preparing the installation of SUSE® Linux Enterprise Server on IBM z Systems. It provides all information needed to prepare the installation on the LPAR and z/VM side.

5 Installation on ARM AArch64

This chapter describes the steps necessary to prepare for the installation of SUSE Linux Enterprise Server on ARM AArch64 computers. It introduces the steps required to prepare for various installation methods. The list of hardware requirements provides an overview of systems supported by SUSE Linux Enterprise Server. Find information about available installation methods and several common known problems. Also learn how to control the installation, provide installation media, and boot with regular methods.

2 Installation on AMD64 and Intel 64

  • Filename: deployment_prep_x86.xml
  • ID: cha.x86
Abstract

This chapter describes the steps necessary to prepare for the installation of SUSE Linux Enterprise Server on AMD64 and Intel 64 computers. It introduces the steps required to prepare for various installation methods. The list of hardware requirements provides an overview of systems supported by SUSE Linux Enterprise Server. Find information about available installation methods and several common known problems. Also learn how to control the installation, provide installation media, and boot with regular methods.

2.1 System Requirements for Operating Linux

  • Filename: deployment_prep_x86_nsysreqs.xml
  • ID: sec.x86.sysreqs

The SUSE® Linux Enterprise Server operating system can be deployed on a wide range of hardware. It is impossible to list all the different combinations of hardware SUSE Linux Enterprise Server supports. However, to provide you with a guide to help you during the planning phase, the minimum requirements are presented here.

If you want to be sure that a given computer configuration will work, find out which platforms have been certified by SUSE. Find a list at https://www.suse.com/yessearch/.

2.1.1 Hardware for Intel 64 and AMD64

The Intel 64 and AMD64 architectures support the simple migration of x86 software to 64 bits. Like the x86 architecture, they constitute a value-for-money alternative.

CPU

All CPUs available on the market to date are supported.

Maximum Number of CPUs

The maximum number of CPUs supported by software design is 8192 for Intel 64 and AMD64. If you plan to use such a large system, verify with our hardware system certification Web page for supported devices, see https://www.suse.com/yessearch/.

Memory Requirements

A minimum of 512 MB of memory is required for a minimal installation. However, the minimum recommended is 1024 MB or 512 MB per CPU on multiprocessor computers. Add 150 MB for a remote installation via HTTP or FTP. Note that these values are only valid for the installation of the operating system—the actual memory requirement in production depends on the system's workload.

Hard Disk Requirements

The disk requirements depend largely on the installation selected and how you use your machine. Minimum requirements for different selections are:

System

Hard Disk Requirements

Minimal System

800 MB - 1GB

Minimal X Window System

1.4 GB

GNOME Desktop

3.5 GB

All patterns

8.5 GB

Using snapshots for virtualization

min. 8 GB

Boot Methods

The computer can be booted from a CD or a network. A special boot server is required to boot over the network. This can be set up with SUSE Linux Enterprise Server.

2.2 Installation Considerations

  • Filename: deployment_prep_x86_choose.xml
  • ID: sec.x86.prep.choose

This section encompasses many factors that need to be considered before installing SUSE Linux Enterprise Server on AMD64 and Intel 64 hardware.

2.2.1 Installation Type

SUSE Linux Enterprise Server is normally installed as an independent operating system. With the introduction of Virtualization, it is also possible to run multiple instances of SUSE Linux Enterprise Server on the same hardware. However, the installation of the VM Host Server is performed like a typical installation with some additional packages. The installation of virtual guests is described in Chapter 9, Guest Installation.

2.2.2 Boot Methods

Depending on the hardware used, the following boot methods are available for the first boot procedure (prior to the installation of SUSE Linux Enterprise Server).

Table 2.1: Boot Options

Boot Option

Use

CD or DVD drive

The simplest booting method. The system requires a locally-available CD-ROM or DVD-ROM drive for this.

Flash disks

Find the images required for creating boot disks on the first CD or DVD in the /boot directory. See also the README in the same directory. Booting from a USB memory stick is only possible if the BIOS of the machine supports this method.

PXE or bootp

Must be supported by the BIOS or by the firmware of the system used. This option requires a boot server in the network. This task can be handled by a separate SUSE Linux Enterprise Server.

Hard disk

SUSE Linux Enterprise Server can also be booted from hard disk. For this, copy the kernel (linux) and the installation system (initrd) from the /boot/loader directory of the first CD or DVD onto the hard disk and add an appropriate entry to the boot loader.

2.2.3 Installation Source

When installing SUSE Linux Enterprise Server, the actual installation data must be available in the network, on a hard disk partition, or on a local DVD. To install from the network, you need an installation server. To make the installation data available, set up any computer in a Unix or Linux environment as an NFS, HTTP, SMB, or FTP server. To make the installation data available from a Windows computer, release the data with SMB.

The installation source is particularly easy to select if you configure an SLP server in the local network. For more information, see Chapter 8, Setting Up the Server Holding the Installation Sources.

2.2.4 Installation Target

Most installations are to a local hard disk. Therefore, it is necessary for the hard disk controllers to be available to the installation system. If a special controller (like a RAID controller) needs an extra kernel module, provide a kernel module update disk to the installation system.

Other installation targets may be various types of block devices that provide sufficient disk space and speed to run an operating system. This includes network block devices like iSCSI or SAN. It is also possible to install on network file systems that offer the standard Unix permissions. However, it may be problematic to boot these, because they must be supported by the initramfs before the actual system can start. Such installations can be useful when you need to start the same system in different locations or you plan to use virtualization features like domain migration.

2.2.5 Different Installation Methods

SUSE Linux Enterprise Server offers several methods for controlling installation:

  • Installation on the console

  • Installation via serial console

  • Installation with AutoYaST

  • Installation with KIWI images

  • Installation via SSH

  • Installation with VNC

By default, the graphical console is used. If you have many similar computers to install, it is advisable to create an AutoYaST configuration file or a KIWI preload image and make this available to the installation process. See also the documentation for AutoYaST at https://www.suse.com/documentation/sles-12/book_autoyast/data/book_autoyast.html and KIWI at http://doc.opensuse.org/projects/kiwi/doc/.

2.3 Boot and Installation Media

  • Filename: deployment_prep_x86_makeavail.xml
  • ID: sec.instserver

When installing the system, the media for booting and for installing the system may be different. All combinations of supported media for booting and installing may be used.

2.3.1 Boot Media

Booting a computer depends on the capabilities of the hardware used and the availability of media for the respective boot option.

Booting from DVD

This is the most common possibility of booting a system. It is straightforward for most computer users, but requires a lot of interaction for every installation process.

Booting from a USB Hard Disk

Depending on the hardware used, it is possible to boot from a USB hard disk. The respective media must be created as described in Section 6.2.2, “PC (AMD64/Intel 64/ARM AArch64): System Start-up”.

Booting from the Network

You can only boot a computer directly from the network if this is supported by the computer's firmware or BIOS. This booting method requires a boot server that provides the needed boot images over the network. The exact protocol depends on your hardware. Commonly you need several services, such as TFTP and DHCP or PXE boot. If you need a boot server, also read Section 10.1.3, “Remote Installation via VNC—PXE Boot and Wake on LAN”.

2.3.2 Installation Media

The installation media contain all the necessary packages and meta information that is necessary to install a SUSE Linux Enterprise Server. These must be available to the installation system after booting for installation. Several possibilities for providing the installation media to the system are available with SUSE Linux Enterprise Server.

Installation from DVD

All necessary data is delivered on the boot media. Depending on the selected installation, a network connection or add-on media may be necessary.

Networked Installation

If you plan to install several systems, providing the installation media over the network makes things a lot easier. It is possible to install from many common protocols, such as NFS, HTTP, FTP, or SMB. For more information on how to run such an installation, refer to Chapter 10, Remote Installation.

2.4 Installation Procedure

  • Filename: deployment_prep_x86_workflow.xml
  • ID: sec.x86.prep.worklfow

This section offers an overview of the steps required for the complete installation of SUSE® Linux Enterprise Server in the required mode. Part II, “The Installation Workflow” contains a full description of how to install and configure the system with YaST.

2.4.1 Booting from a Local Interchangeable Drive

DVD-ROM and USB storage devices can be used for installation purposes. Adjust your computer to your needs:

  1. Make sure that the drive is entered as a bootable drive in the BIOS.

  2. Insert the boot medium in the drive and start the boot procedure.

  3. The installation boot menu of SUSE Linux Enterprise Server allows transferring different parameters to the installation system. See also Section 10.2.2, “Using Custom Boot Options”. If the installation should be performed over the network, specify the installation source here.

  4. If unexpected problems arise during installation, use safe settings to boot.

2.4.2 Installing over the Network

An installation server is required to perform the installation by using a network source. The procedure for installing this server is outlined in Chapter 8, Setting Up the Server Holding the Installation Sources.

If you have an SLP server, select SLP as the installation source in the first boot screen. During the boot procedure, select which of the available installation sources to use.

If the DVD is available on the network, use it as an installation source. In this case, specify the parameter install=<URL> with suitable values at the boot prompt. Find a more detailed description of this parameter in Section 10.2.2, “Using Custom Boot Options”.

2.5 Controlling the Installation

  • Filename: deployment_prep_x86_boot.xml
  • ID: sec.prep.boot

Control the installation in one of several ways. The method most frequently used is to install SUSE® Linux Enterprise Server from the computer console. Other options are available for different situations.

2.5.1 Installation on the Computer Console

The simplest way to install SUSE Linux Enterprise Server is using the computer console. With this method, a graphical installation program guides you through the installation. This installation method is discussed in detail in Chapter 6, Installation with YaST.

You can still perform the installation on the console without a working graphics mode. The text-based installation program offers the same functionality as the graphical version. Find some hints about navigation in this mode in Section 5.1, “Navigation in Modules”.

2.5.2 Installation Using a Serial Console

For this installation method, you need a second computer that is connected by a null modem cable to the computer on which to install SUSE Linux Enterprise Server. Depending on the hardware, even the firmware or BIOS of the computer may already be accessible to the serial console. If this is possible, you can carry out the entire installation using this method. To activate the serial console installation, specify the additional console=ttyS0 parameter at the boot prompt. This should be done after the boot process has completed and before the installation system starts.

On most computers, there are two serial interfaces, ttyS0 and ttyS1. For the installation, you need a terminal program like minicom or screen. To initiate the serial connection, launch the screen program in a local console by entering the following command:

screen /dev/ttyS0 9600

This means that screen listens to the first serial port with a baud rate of 9600. From this point on, the installation proceeds similarly to the text-based installation over this terminal.

2.5.3 Installation with SSH

If you do not have direct access to the machine and the installation initiated from a management console, you can control the entire installation process over the network. To do this, enter the parameters ssh=1 and ssh.password=SECRET at the boot prompt. An SSH daemon is then launched in the system and you can log in as user root with the password SECRET.

To connect, use ssh -X. X-Forwarding over SSH is supported, if you have a local X server available. Otherwise, YaST provides a text interface over ncurses. YaST then guides you through the installation. This procedure is described in detail in Section 10.1.5, “Simple Remote Installation via SSH—Dynamic Network Configuration”.

If you do not have a DHCP server available in your local network, manually assign an IP address to the installation system. Do this by entering the option HostIP=IPADDR at the boot prompt.

2.5.4 Installation over VNC

If you do not have direct access to the system, but want a graphical installation, install SUSE Linux Enterprise Server over VNC. This method is described in detail in Section 10.3.1, “VNC Installation”.

As suitable VNC clients are also available for other operating systems, such as Microsoft Windows and mac OS, the installation can also be controlled from computers running those operating systems.

2.5.5 Installation with AutoYaST

If you need to install SUSE Linux Enterprise Server on several computers with similar hardware, it is recommended you perform the installations using AutoYaST. In this case, start by installing one SUSE Linux Enterprise Server and use this to create the necessary AutoYaST configuration files.

2.6 Dealing with Boot and Installation Problems

  • Filename: x86_inst_problem.xml
  • ID: sec.bootproblem

Prior to delivery, SUSE® Linux Enterprise Server is subjected to an extensive test program. Despite this, problems occasionally occur during boot or installation.

2.6.1 Problems Booting

Boot problems may prevent the YaST installer from starting on your system. Another symptom is when your system does not boot after the installation has been completed.

Installed System Boots, Not Media

Change your computer's firmware or BIOS so that the boot sequence is correct. To do this, consult the manual for your hardware.

The Computer Hangs

Change the console on your computer so that the kernel outputs are visible. Be sure to check the last outputs. This is normally done by pressing CtrlAltF10. If you cannot resolve the problem, consult the SUSE Linux Enterprise Server support staff. To log all system messages at boot time, use a serial connection as described in Section 2.5, “Controlling the Installation”.

Boot Disk

The boot disk is a useful interim solution if you have difficulties setting the other configurations or if you want to postpone the decision regarding the final boot mechanism. For more details on creating boot disks, see grub2-mkrescue.

Virus Warning after Installation

There are BIOS variants that check the structure of the boot sector (MBR) and erroneously display a virus warning after the installation of GRUB 2. Solve this problem by entering the BIOS and looking for corresponding adjustable settings. For example, switch off virus protection. You can switch this option back on again later. It is unnecessary, however, if Linux is the only operating system you use.

2.6.2 Problems Installing

If an unexpected problem occurs during installation, information is needed to determine the cause of the problem. Use the following directions to help with troubleshooting:

  • Check the outputs on the various consoles. You can switch consoles with the key combination CtrlAltFn. For example, obtain a shell in which to execute various commands by pressing CtrlAltF2.

  • Try launching the installation with Safe Settings (press F5 on the installation screen and choose Safe Settings). If the installation works without problems in this case, there is an incompatibility that causes either ACPI or APIC to fail. In some cases, a BIOS or firmware update fixes this problem.

  • Check the system messages on a console in the installation system by entering the command dmesg -T.

2.6.3 Redirecting the Boot Source to the Boot DVD

To simplify the installation process and avoid accidental installations, the default setting on the installation DVD for SUSE Linux Enterprise Server is that your system is booted from the first hard disk. At this point, an installed boot loader normally takes over control of the system. This means that the boot DVD can stay in the drive during an installation. To start the installation, choose one of the installation possibilities in the boot menu of the media.

3 Installation on IBM POWER

  • Filename: deployment_prep_power.xml
  • ID: cha.power
Abstract

This chapter describes the procedure for preparing the installation of SUSE® Linux Enterprise Server on IBM POWER systems.

3.1 Requirements

  • Filename: deployment_prep_power_requirements.xml
  • ID: sec.power.requirements

A standard installation requires at least 512 MB of RAM. The installation of a standard system with the GNOME desktop requires at least 3.5 GB of free hard disk space; a complete installation requires approximately 8.5 GB.

3.1.1 Hardware Requirements

The SUSE® Linux Enterprise Server operating system can be operated on IBM POWER8 servers. To provide you with a guide to help you during the planning phase, the minimum requirements are presented here.

If you want to be sure that a given computer configuration will work, check the database of hardware certified by SUSE. Find a list of certified hardware at http://www.suse.com/yessearch/Search.jsp.

SUSE Linux Enterprise Server may support additional IBM POWER systems not listed below. For the latest information, see the IBM Information Center for Linux at http://www.ibm.com/support/knowledgecenter/linuxonibm/liaam/liaamdistros.htm.

Find up-to-date firmware at IBM FixCentral (http://www.ibm.com/support/fixcentral/). Select your system from the Product Group list. Additional software is available from the IBM PowerLinux Tools Repository. The IBM Tools Repository is also called the Yum Repository. For more information about using the IBM PowerLinux Tools Repository, see https://ibm.biz/Bdxn3N.

3.1.1.1 IBM POWER8 Processor-Based Servers

All POWER8 servers are supported that are PowerKVM-capable.

  • 8247-21L (IBM Power® System S120L)

  • 8247-22L (IBM Power System S220L)

  • 8284-22A (IBM Power System S2200)

  • 8286-41A (IBM Power System S1400)

  • 8286-42A (IBM Power System S2400)

3.2 Preparation

  • Filename: deployment_prep_power_preparing.xml
  • ID: cha.power.prep

This section describes the preparatory steps that must be taken before the actual installation of SUSE Linux Enterprise Server. The installation procedure depends on the system used. The following methods are supported:

If SUSE® Linux Enterprise Server needs to be installed on several systems or partitions, it is recommended you create a network installation source. The same source can also be used for the concurrent installation on several partitions or several systems. The configuration of a network installation source is described in Section 8.1, “Setting Up an Installation Server Using YaST”.

3.2.1 Installation on Servers with IBM PowerKVM using Kimchi

This section covers the preparatory steps for installing on IBM PowerLinux systems with PowerKVM. It explains the installation from an ISO image with the Kimchi Web interface. Kimchi is a tool for administrating IBM PowerKVM.

This section assumes you have PowerKVM running on your IBM PowerLinux server. If PowerKVM is not preinstalled see Configuring IBM PowerKVM on Power Systems at http://www.ibm.com/support/knowledgecenter/linuxonibm/liabp/liabpkickoff.htm for installing and setting up PowerKVM.

3.2.1.1 Creating a SUSE Linux Enterprise Server Template with Kimchi

Templates are the installation source for PowerKVM guests. You can create a template, edit an existing template, or clone a template. To clone a template from an existing guest, that guest must be deactivated.

Procedure 3.1: Creating a Template with Kimchi
  1. In the Web browser, enter the URL of the PowerLinux server where PowerKVM is running, for example https://POWERLINUX_IP:8001 (replace POWERLINUX_IP with the IP address of your system).

  2. Click the Templates tab to activate the Templates page.

  3. Click the green plus sign (+) to create the SUSE Linux Enterprise Server template.

  4. On the Add Template dialog, select from the following options:

    Local ISO Image

    Select to scan storage pools for installation ISO images available on the system.

    Local Image File

    Select to specify a path to a local image file.

    Remote ISO file

    Select to specify a remote location for an installation ISO image.

  5. Select the ISO file that you want to use to create a guest and click Create Templates from Selected ISO.

  6. To configure the newly created template, click Actions › Edit, and change the default values as required by your workload.

For more information, see Setting up a template using Kimchi at http://www.ibm.com/support/knowledgecenter/linuxonibm/liabp/liabpkimchitemplate.htm.

3.2.1.2 Installing SUSE Linux Enterprise Server as a Guest with Kimchi

  1. In the Web browser, enter the URL of the PowerLinux server where PowerKVM is running, for example https://POWERLINUX_IP:8001 (replace POWERLINUX_IP with the IP address of your system).

  2. Click the Guests tab to activate the Guests page.

  3. Click the green plus sign (+) to create the SUSE Linux Enterprise Server guest.

  4. Enter a Virtual Machine Name for the SUSE Linux Enterprise Server guest.

    Choose the SUSE Linux Enterprise Server template created in Section 3.2.1.1, “Creating a SUSE Linux Enterprise Server Template with Kimchi” and click Create.

  5. After the guest is created, it is ready to be started. Click the red power button to start the SUSE Linux Enterprise Server guest. Alternatively, select Actions › Start.

  6. Click Actions › Connect, and connect your VNC viewer to the installation process as outlined in Section 10.3.1.2, “Connecting to the Installation Program”.

Tip
Tip: Creating Multiple Guests

To create multiple guests of a similar type, select Clone from the Actions menu of an existing guest.

Now you can continue with the default installation via VNC as described in Section 6.3, “Steps of the Installation”.

3.2.2 Installation on Servers with IBM PowerKVM using virt-install

Alternatively to installing with Kimchi, use the virt-install command line tool to install on servers with IBM PowerKVM. This is especially useful you need to install multiple virtual machines on IBM PowerLinux Server systems. virt-install allows many installation scenarios; in the following a remote installation scenario via VNC and PXE boot is outlined. For more information about virt-install, see Section 9.2, “Installing from the Command Line with virt-install.

Prepare a repository with the installation sources and PXE boot enabled target system as described in Section 10.1.3, “Remote Installation via VNC—PXE Boot and Wake on LAN”.

On the command line, enter something similar as follows (adjust the options according to your needs and matching your hardware):

virt-install --name server_sle12 --memory 4096 --vcpus=2 --pxe \
--graphics vnc --os-variant sles11 \
--disk pool=default,size=3000,format=qcow2,allocation=1G,bus=virtio \
-w mac=MAC_ADDRESS,model=spapr-vlan

It will use VNC graphics, and it will automatically launch the graphical client. Complete the installation as described in Section 6.3, “Steps of the Installation”.

3.2.3 Installation in a Partition Using IVM

This guide helps you install SUSE Linux Enterprise Server on a Power Systems server partition using the Integrated Virtualization Manager (IVM) Web interface. Before starting the installation, make sure the following requirements are met:

  • the Linux on Power system is powered on

  • the Virtual I/O server is installed

  • the IVM is initially configured

Procedure 3.2: Log in to the IVM Web interface
  1. Open a Web browser window, and connect using the HTTP or HTTPS protocol to the IP address that was assigned to the IVM during the installation process (for example, https://IP_ADDRESS). The Welcome window is displayed.

  2. Log in as the user padmin, providing the password that you defined during the installation process. The IVM interface is displayed.

  3. Select View/Modify Virtual Ethernet.

  4. Click Initialize Virtual Ethernet to provide Ethernet connectivity among the partitions.

  5. When the Virtual Ethernet is initialized, click Apply.

  6. If your installation requires external networking, create a virtual Ethernet bridge.

    1. Select the Virtual Ethernet Bridge tab.

    2. Select the physical adapter to bridge and proceed with Apply.

Next, create a partition, following these steps:

Procedure 3.3: Create a Partition
  1. In the IVM Web interface, click View/Modify Partition › Create Partition.

  2. Enter a name for the partition. To advance to the next step, click Next on this and the following steps.

  3. Specify memory for your partition. If you have created a shared memory pool, your partitions can share memory. Otherwise, select Dedicated.

  4. Specify the number of processors and the processing mode for the partition.

  5. Specify a virtual Ethernet for the partition. If you do not want to configure an adapter, select none for the virtual Ethernet.

  6. Create a new virtual disk or assign existing virtual disks and physical volumes that are not currently assigned to a partition.

  7. Verify the Virtual disk name and Storage pool name for your disk and specify a Virtual disk size.

  8. Configure optical devices for your partition by expanding the Physical Optical Devices and Virtual Optical Devices and select the device(s) you want to assign to the partition.

  9. Verify your partition configuration settings and click Finish. The partition is created and available from the View/Modify Partitions list.

Now activate the partition you have created:

Procedure 3.4: Activate the Partition
  1. In the IVM Web interface, click View/Modify Partition and select the box next to the partition you would like to activate.

  2. Select More Tasks.

  3. Select Open a terminal window.

  4. Click Activate next to the partition.

  5. In the terminal window, enter 1 to start the system management services (SMS).

The machine is set up now and you can boot into the installation:

Procedure 3.5: Boot the Linux Installation
  1. At the Boot selection window, enter 1 to select the SMS Menu. Enter 1 before the firmware boot screen is completely shown on the display, because it will disappear when complete. If you miss the screen, reboot the system.

  2. At this time, you can insert the Virtual I/O Server (VIOS) media disk into the disk drive.

  3. Enter 2 to continue to the password entry on the Language selection menu. Enter the password for the admin ID.

  4. On the main SMS menu, enter 5 to choose Select Boot Options.

  5. Enter 1 to select Install/Boot Device.

  6. Enter 7 to view all of the available boot devices.

  7. Enter the number corresponding to the device you want to use. If your device is not listed, enter N to display more.

  8. Enter 2 to perform a Normal Mode Boot.

  9. Enter 1 to leave the SMS menu and to start the boot process.

  10. At the boot prompt from the installer, type

    install vnc=1
    vncpassword=VNC_PASSWORD

    Replace VNC_PASSWORD with a password of your choice (minimum length is eight characters) and press Enter to start the installation of SUSE Linux Enterprise Server. The kernel will begin loading.

After the kernel has started to load, the installer needs some information from the system in order to set up a VNC session. You must have a valid TCP/IP stack in order to use VNC. Either use DHCP or manually define your networking information using directions provided by the installer.

Procedure 3.6: Start the VNC Session
  1. On the Network device window, select eth0 as your network device. Select OK and press Enter.

  2. Test the installation media. Alternatively, proceed without the test by selecting Skip.

  3. After the system has started the VNC server, you will see a message to connect your VNC client followed by an IP address. Take note of this IP address.

  4. Start a VNC client on your laptop or PC. Enter the IP address from the previous step followed by :1, for example 192.168.2.103:1.

  5. Complete the installation as described in Section 6.3, “Steps of the Installation”.

3.2.4 Installation on Servers with no Open Power Abstraction Layer

Use this information to install Linux using a serial console or using a monitor and keyboard on a Power Systems server. This installation assumes an unmanaged (stand-alone) system that is ready to boot.

  1. Power on your system by selecting Power On from the Power On/Off System menu. When asked if you want to continue using the console, enter 0 to continue doing so.

  2. Insert the SUSE Linux Enterprise Server installation media into the disk drive.

  3. From the Select Language window, enter 2 to continue to booting.

  4. Enter 1 to accept the license agreement.

  5. At the Boot selection window, enter 1 to select the SMS Menu. Enter 1 before the firmware boot screen is completely shown on the display, because it will disappear when complete. If you miss the screen, reboot the system.

  6. Enter 2 to continue to the password entry on the Language selection menu. Enter the password for the admin ID.

  7. On the main SMS menu, enter 5 to choose Select Boot Options.

  8. Enter 7 to view all of the available boot devices.

  9. Enter the number corresponding to the device you want to use. If your device is not listed, enter N to display more.

  10. Enter 2 to perform a Normal Mode Boot.

  11. Enter 1 to leave the SMS menu and to start the boot process.

  12. At the boot prompt from the installer, type

    install vnc=1
    vncpassword=VNC_PASSWORD

    Replace VNC_PASSWORD with a password of your choice (minimum length is eight characters) and press Enter to start the installation of SUSE Linux Enterprise Server. The kernel will begin loading.

After the kernel has started to load, the installer needs some information from the system in order to set up a VNC session. You must have a valid TCP/IP stack in order to use VNC. Either use DHCP or manually define your networking information using directions provided by the installer.

Procedure 3.7: Start the VNC Session
  1. On the Network device window, select eth0 as your network device. Select OK and press Enter.

  2. Test the installation media. Alternatively, proceed without the test by selecting Skip.

  3. After the system has started the VNC server, you will see a message to connect your VNC client followed by an IP address. Take note of this IP address.

  4. Start a VNC client on your laptop or PC. Enter the IP address from the previous step followed by :1, for example 192.168.2.103:1.

  5. Complete the installation as described in Section 6.3, “Steps of the Installation”.

3.3 For More Information

  • Filename: deployment_prep_power_info.xml
  • ID: sec.power.info

More information on IBM PowerLinux is available from SUSE and IBM:

  • The SUSE Support Knowledge Base at https://www.suse.com/support/kb/ is an effective help tool for assisting customers in solving problems. Search the knowledge base on SUSE Linux Enterprise Server using keywords like POWER or PowerKVM.

  • Find security alerts at https://www.suse.com/support/security/. SUSE also maintains two security-related mailing lists to which anyone may subscribe.

    • suse-security — General discussion of security regarding Linux and SUSE. All security alerts for SUSE Linux Enterprise Server are sent to this list.

    • suse-security-announce — The SUSE mailing list exclusively for security alerts.

  • In case of hardware errors, check the control panel for any codes that might be displayed. You can look up any codes that are displayed at the IBM Power Systems Hardware Information Center at https://ibm.biz/Bdxn3T.

  • For troubleshooting tips, see the IBM PowerLinux FAQ topic in the Information Center at https://ibm.biz/Bdxn35.

  • To participate in the linuxppc-dev mailing list, register using the forms at http://lists.ozlabs.org/listinfo/linuxppc-dev/.

4 Installation on IBM z Systems

  • Filename: deployment_prep_zseries.xml
  • ID: cha.zseries
Abstract

This chapter describes the procedure for preparing the installation of SUSE® Linux Enterprise Server on IBM z Systems. It provides all information needed to prepare the installation on the LPAR and z/VM side.

4.1 General Information and Requirements

  • Filename: deployment_prep_zseries_info_i.xml
  • ID: cha.info_sysreq

This section gives basic information about the system requirements (like supported hardware), level of MicroCode, and software. It also covers the different installation types and how to do an IPL for the first installation. For detailed technical information about IBM z Systems on SUSE Linux Enterprise Server refer to http://www.ibm.com/developerworks/linux/linux390/documentation_suse.html.

4.1.1 System Requirements

This section provides a list of hardware for IBM z Systems supported by SUSE Linux Enterprise Server. Next, the level of the MicroCode (MCL) used in your IBM z Systems system, which is very important for the installation, is covered. Additional software to install and use for installation is mentioned at the end of this section.

4.1.1.1 Hardware

SUSE Linux Enterprise Server has run successfully on the following platforms:

  • IBM zEnterprise System z196 (2817)

  • IBM zEnterprise System z114 (2818)

  • IBM zEnterprise EC12 (zEC12) (2827)

  • IBM zEnterprise BC12 (zBC12) (2828)

  • IBM z Systems z13 (2964)

  • IBM z Systems z13s (2965)

  • IBM LinuxONE Emperor (2964)

  • IBM LinuxONE Rockhopper (2965)

4.1.1.1.1 Memory Requirements

Different installation methods have different memory requirements during installation. After installation is completed, the system administrator may reduce memory to the desired size. SUSE recommends using:

1 GB

For installation under z/VM.

1 GB

For installation under LPAR.

1 GB

For installation under KVM.

Note
Note: Memory Requirements with Remote Installation Sources

For installation from NFS, FTP, or SMB installation sources or whenever VNC is used, 512MB of memory is required as a minimum. Otherwise, the installation attempt is likely to fail. Further note that the number of devices visible to the z/VM guest or LPAR image affects memory requirements. Installation with literally hundreds of accessible devices (even if unused for the installation) may require more memory.

4.1.1.1.2 Disk Space Requirements

The disk requirements depend largely on the installation. Commonly, you need more space than the installation software itself needs to have a system that works properly. Minimal requirements for different selections are:

800 MB

Minimal Installation

1.4 GB

Minimal Installation + Base System

2.6 GB

Default Installation

3.6 GB+

Recommended (this is with graphical desktop, development packages and Java).

4.1.1.1.3 Network Connection

A network connection is needed to communicate with your SUSE Linux Enterprise Server system. This can be one or more of the following connections or network cards:

  • OSA Express Ethernet (including Fast and Gigabit Ethernet)

  • HiperSockets or Guest LAN

  • 10 GBE, VSWITCH

  • RoCE (RDMA over Converged Ethernet)

The following interfaces are still included, but no longer supported:

  • CTC (or virtual CTC)

  • ESCON

  • IP network interface for IUCV

For installations under KVM make sure the following requirements are met to enable the VM Guest to access the network transparently:

  • The virtual network interface is connected to a host network interface.

  • The host network interface is connected to a network in which the virtual server will participate.

  • If the host is configured to have a redundant network connection by grouping two independent OSA network ports into a bonded network interface, the identifier for the bonded network interface is bond0 (or, if more than one bonded interface exists, bond1, bond2, ...).

  • If the host network connection has not been set up redundantly, the identifier of the single network interface needs to be used. It has the form enccw0.0.NNNN, where NNNN is the device number of the desired network interface.

4.1.1.2 MicroCode Level, APARs, and Fixes

Documentation about restrictions and requirements for this release of SUSE Linux Enterprise Server be found on IBM developerWorks at http://www.ibm.com/developerworks/linux/linux390/documentation_suse.html. It is recommended always to use the highest service level available. Contact your IBM support for minimum requirements.

4.1.1.2.1 z/VM
  • z/VM 5.4

  • z/VM 6.2

  • z/VM 6.3, we strongly suggest installing the APAR VM65419 (or higher) to improve the output of qclib.

Negotiate the order of installation with your IBM support, because it might be necessary to activate the VM APARs before installing the new MicroCode levels.

4.1.1.3 Software

When installing SUSE Linux Enterprise Server via non-Linux–based NFS or FTP, you might experience problems with NFS or FTP server software. The Windows* standard FTP server can cause errors, so installing via SMB on these machines is generally recommended.

To connect to the SUSE Linux Enterprise Server installation system, one of the following methods is required (SSH or VNC are recommended):

SSH with Terminal Emulation (xterm compatible)

SSH is a standard Unix tool that should be present on any Unix or Linux system. For Windows, there is an SSH client called Putty. It is free to use and is available from http://www.chiark.greenend.org.uk/~sgtatham/putty/.

VNC Client

For Linux, a VNC client called vncviewer is included in SUSE Linux Enterprise Server as part of the tightvnc package. For Windows, TightVNC is also available. Download it from http://www.tightvnc.com/.

X Server

Find a suitable X server implementation on any Linux or Unix workstation. There are many commercial X Window System environments for Windows and macOS*. Some can be downloaded as free trial versions. A trial version of the Mocha X Server from MochaSoft can be obtained at http://www.mochasoft.dk/freeware/x11.htm.

Tip
Tip: Additional Information

Consult the README file located in the root directory of DVD 1 of your SUSE Linux Enterprise Server before installing SUSE Linux Enterprise Server on IBM z Systems. This file complements this documentation.

4.1.2 Installation Types

This section gives an overview of the different types of installation possible with SUSE Linux Enterprise Server for IBM z Systems:

LPAR

Installation of SUSE Linux Enterprise Server using a logical partition (LPAR).

z/VM

Installation of SUSE Linux Enterprise Server as a guest operating system within z/VM.

KVM

Installation of SUSE Linux Enterprise Server as a guest operating system within KVM.

Depending on the mode of installation (LPAR or z/VM), there are different possibilities for starting the installation process and IPLing the installed system.

4.1.2.1 LPAR

If you install SUSE Linux Enterprise Server for IBM z Systems into a logical partition (LPAR), assign memory and processors to the instance. Installing into LPAR is recommended for highly loaded production machines. Running in LPAR also makes higher security standards available. Networking between LPARs is possible over external interfaces or Hipersockets. In case you plan to use your installation for virtualization with KVM, installing into LPAR is highly recommended.

4.1.2.2 z/VM

Running SUSE Linux Enterprise Server for IBM z Systems in z/VM means that SUSE Linux Enterprise Server is a guest system within z/VM. An advantage of this mode is that you have full control over SUSE Linux Enterprise Server from z/VM. This is very helpful for kernel development or kernel-based debugging. It is also very easy to add or remove hardware to and from Linux guests. Creating additional SUSE Linux Enterprise Server guests is simple and you can run hundreds of Linux instances simultaneously.

4.1.2.3 KVM Guest

Being able to install SUSE Linux Enterprise Server for IBM z Systems as a KVM guest requires a KVM host server instance installed into LPAR. For details on the guest installation, refer to Procedure 4.3, “Overview of a KVM Guest Installation”.

4.1.3 IPL Options

This section provides the information needed to do an IPL for the first installation. Depending on the type of installation, different options need to be used. The VM reader, load from CD-ROM or server and load from an SCSI-attached DVD-ROM options are discussed. Installing the software packages, which is done over the network, does not require the IPL medium.

4.1.3.1 VM Reader

To IPL from a VM reader, transfer the necessary files into the reader first. For convenience of administration, it is recommended to create a user linuxmnt that owns a minidisk with the files and scripts needed for IPL. This minidisk is then accessed read-only by the Linux guests.

4.1.3.2 Load from Removable Media or Server

For IPLing into an LPAR, it is possible to either load the kernel image directly from the SE's or the HMC's CD/DVD-ROM device or from any remote system accessible through FTP. This function can be performed from the HMC. The installation process requires a file with a mapping of the location of the installation data in the file system and the memory locations where the data is to be copied.

For SUSE Linux Enterprise Server, there are two such files. Both are located in the root directory of the file system of DVD 1:

  • suse.ins, for which to work you need to set up network access in Linuxrc before starting the installation.

  • susehmc.ins which allows installing without network access.

In the left navigation pane of the HMC expand Systems Management › Systems and select the mainframe system you want to work with. Choose the LPAR where you want to boot SUSE Linux Enterprise Server from the table of LPARs and select Load from Removable Media or Server.

Now either choose Hardware Management Console CD-ROM/DVD or FTP Source. If having chosen the latter option, provide the servers address or name and your credentials. If the appropriate .ins file is not located in the root directory of the server, provide the path to this file. Continue to the Select the software to load menu and select the appropriate .ins entry. Start the installation with OK.

4.1.3.3 Load from SCSI-Attached DVD

To IPL from an SCSI DVD, you need access to an FCP adapter connected to a DVD drive. You need the values for WWPN and LUN from the SCSI drive. For details, see Section 4.2.4.1.2, “IPL from FCP-Attached SCSI DVD”.

4.1.3.4 Load from the Network with zPXE

IPLing from the Network with zPXE requires a Cobbler server providing the kernel, RAM disk and a parmfile. It is initiated by running the ZPXE EXEC script. See Section 4.2.1.3, “Using a Cobbler Server for zPXE” for details. zPXE is only available on z/VM.

4.2 Preparing for Installation

  • Filename: deployment_prep_zseries_prep_i.xml
  • ID: sec.zseries.prep

Learn how to make the data accessible for installation, install SUSE Linux Enterprise Server using different methods, and prepare and use the IPL of the SUSE Linux Enterprise Server installation system. Also find out about network configuration and network installation.

4.2.1 Making the Installation Data Available

This section provides detailed information about making the SUSE Linux Enterprise Server IBM z Systems installation data accessible for installation. Depending on your computer and system environment, choose between NFS or FTP installation. If you are running Microsoft Windows workstations in your environment, you can use the Windows network (including the SMB protocol) to install SUSE Linux Enterprise Server on your IBM z Systems system.

Tip
Tip: IPL from DVD

Starting with Service Pack 1 of SUSE Linux Enterprise Server Version 10, it is possible to IPL from DVD and use the DVD as the installation medium. This is very convenient if you have restrictions setting up an installation server providing installation media over your network. The prerequisite is an FCP-attached SCSI DVD Drive.

Note
Note: No Installation From Hard Disk

It is not possible to install from hard disk by putting the content of the DVD to a partition on a DASD.

4.2.1.1 Using a Linux Workstation or SUSE Linux Enterprise Server DVD

If you have a Linux workstation running in your computer environment, use the workstation to provide the installation data to the IBM z Systems installation process by NFS or FTP. If the Linux workstation runs under SUSE Linux Enterprise Server, you can set up an installation server (NFS or FTP) using the YaST Installation Server module as described in Section 8.1, “Setting Up an Installation Server Using YaST”.

4.2.1.1.1 Over NFS

Use NFS (network file system) to make the installation media available.

Important
Important: Exporting Mounted Devices with NFS

Exporting the file system root (/) does not imply the export of mounted devices, such as DVD. Explicitly name the mount point in /etc/exports:

/media/dvd  *(ro)

After changing this file, restart the NFS server with the command sudo systemctl restart nfsserver.

4.2.1.1.2 Over FTP

Setting up an FTP server on a Linux system involves the installation and configuration of the server software like pure-ftpd or vsftpd. If you are using SUSE Linux Enterprise Server, refer to Chapter 32, Setting Up an FTP Server with YaST for installation instructions. Downloading the installation data via anonymous login is not supported, therefore you need to configure the FTP server to support user authentication.

4.2.1.1.3 SUSE Linux Enterprise Server on DVD

DVD1 of the SUSE Linux Enterprise Server for IBM z Systems contains a bootable Linux image for Intel-based workstations and an image for z Systems.

For Intel-based workstations, boot from this DVD, answer the questions regarding your language and keyboard layout, and select Start rescue system. You need at least 64 MB RAM for this. No disk space is needed because the entire rescue system resides in the workstation's RAM. This approach takes some Linux and networking experience, because you need to set up the networking of the workstation manually.

For z Systems, IPL your LPAR/VM guest from this DVD as described in Section 4.2.4.1.2, “IPL from FCP-Attached SCSI DVD”. After entering your network parameters, the installation system treats the DVD as the source of installation data. Because z Systems cannot have an X11-capable terminal attached directly, choose between VNC or SSH installation. SSH also provides a graphical installation by tunneling the X connection through SSH with ssh -X.

4.2.1.2 Using a Microsoft Windows Workstation

If there is a Microsoft Windows workstation available in your network, use this computer to make the installation media available. The easiest way to do this is to use the SMB protocol, already included in the Windows operating system. Be sure to activate SMB over TCP/IP as this enables the encapsulation of SMB packages into TCP/IP packages. Find details in the Windows online help or other Windows-related documentation that covers networking. Another option is to use FTP. This also requires some third-party software for Windows.

4.2.1.2.1 With SMB

To make the installation media available with SMB, insert the SUSE Linux Enterprise Server DVD 1 into the DVD drive of the Windows workstation. Then create a new share using the DVD-ROM drive's letter and make it available for everyone in the network.

The installation path in YaST can be:

smb://DOMAIN;USER:PW@SERVERNAME/SHAREPATH

Where the placeholders mean:

DOMAIN

Optional workgroup or active directory domain.

USER , PW

Optional user name and password of a user who can access this server and its share.

SERVERNAME

The name of the server that hosts the share(s).

SHAREPATH

The path to the share(s).

4.2.1.2.2 With NFS

Refer to the documentation provided with the third party product that enables NFS server services for your Windows workstation. The DVD-ROM drive containing the SUSE Linux Enterprise Server DVDs must be in the available NFS path.

4.2.1.2.3 With FTP

Refer to the documentation provided with the third party product that is enabling FTP server services on your Windows workstation. The DVD-ROM drive containing the SUSE Linux Enterprise Server DVDs must be in the available FTP path.

The FTP server that is bundled with some Microsoft Windows releases implements only a subset of the FTP commands, and it is not suitable for providing the installation data. If this applies to your Windows workstation, use a third party FTP server providing the required features.

4.2.1.2.4 Using an FCP-Attached SCSI DVD Drive

After you IPLed from the SCSI DVD as described in Section 4.1.3.3, “Load from SCSI-Attached DVD”, the installation system uses the DVD as the installation medium. In that case, you do not need the installation media on an FTP, NFS, or SMB server. However, you need the network configuration data for your SUSE Linux Enterprise Server, because you must set up the network during the installation to perform a graphical installation by VNC or by X.

4.2.1.3 Using a Cobbler Server for zPXE

IPLing from the network requires a Cobbler server, to provide the kernel, initrd, and the installation data. Preparing the Cobbler server requires four steps:

  • Importing the Installation Data

  • Adding a Distribution

  • Adding Profiles

  • Adding Systems

4.2.1.3.1 Importing the Installation Data

Importing the media requires the installation source to be available on the Cobbler server—either from DVD or from a network source. Run the following command to import the data:

cobbler import --path=PATH1 --name=IDENTIFIER2 --arch=s390x

1

Mount point of the installation data.

2

A string identifying the imported product, for example sles12_s390x. This string is used as the name for the subdirectory where the installation data is copied to. On a Cobbler server running on SUSE Linux Enterprise this is /srv/www/cobbler/ks_mirror/IDENTIFIER. This path may be different if Cobbler runs on another operating system.

4.2.1.3.2 Adding a Distribution

By adding a distribution, you tell Cobbler to provide the kernel and the initrd required to IPL via zPXE. Run the following command on the Cobbler server to add SUSE Linux Enterprise Server for IBM z Systems:

cobbler distro add --arch=s390 --breed=suse --name="IDENTIFIER"1 \
  --os-version=sles122 \
  --initrd=/srv/www/cobbler/ks_mirror/IDENTIFIER/boot/s390x/initrd3 \
  --kernel=/srv/www/cobbler/ks_mirror/IDENTIFIER/boot/s390x/linux4 \
  --kopts="install=http://cobbler.example.com/cobbler/ks_mirror/IDENTIFIER"5

1

Custom identifier for the distribution, for example SLES 12 SP3 z Systems. Must be unique.

2

Operating system identifier. Use sles12.

3

Path to the initrd. The first part of the path (/srv/www/cobbler/ks_mirror/IDENTIFIER/) depends on the location where Cobbler imported the data and the subdirectory name you chose when importing the installation data.

4

Path to the kernel. The first part of the path (/srv/www/cobbler/ks_mirror/IDENTIFIER/) depends on the location where Cobbler imported the data and the subdirectory name you chose when importing the installation data.

5

URl to the installation directory on the Cobbler server.

4.2.1.3.3 Adjusting the Profile

When adding a distribution (see Section 4.2.1.3.2, “Adding a Distribution”) a profile with the corresponding IDENTIFIER is automatically generated. Use the following command to make a few required adjustments:

cobbler distro edit \
--name=IDENTIFIER1 --os-version=sles102 --ksmeta=""3
--kopts="install=http://cobbler.example.com/cobbler/ks_mirror/IDENTIFIER"4

1

Identifier for the profile. Use the same string as specified when having added the distribution.

2

Operating system version. Distribution to which the profile should apply. You must use the string specified with --name=IDENTIFIER in the importing step here.

3

Option needed for templating kickstart files. Not used for SUSE, so set to an empty value as specified in the example.

4

Space-separated list of kernel parameters. Should include at least the install parameter as shown in the example.

4.2.1.3.4 Adding Systems

The last step that is required is to add systems to the Cobbler server. A system addition needs to be done for every z Systems guest that should boot via zPXE. Guests are identified via their z/VM user ID (in the following example, an ID called linux01 is assumed). Note that this ID needs to be a lowercase string. To add a system, run the following command:

cobbler system add --name=linux01 --hostname=linux01.example.com \
--profile=IDENTIFIER --interface=qdio \
--ip-address=192.168.2.103 --subnet=192.168.2.255 --netmask=255.255.255.0 \
--name-servers=192.168.1.116 --name-servers-search=example.com \
--gateway=192.168.2.1 --kopts="KERNEL_OPTIONS"

With the --kopts option you can specify the kernel and installation parameters you would normally specify in the parmfile. The parameters are entered as a space-separated list in the form of PARAMETER1=VALUE1 PARAMETER2=VALUE2. The installer will prompt you for missing parameters. For a completely automated installation you need to specify all parameters for networking, DASDs and provide an AutoYaST file. The following shows an example for a guest equipped with an OSA interface using the same network parameters as above.

--kopts=" \
AutoYaST=http://192.168.0.5/autoinst.xml \
Hostname=linux01.example.com \
Domain=example.com \
HostIP=192.168.2.103 \
Gateway=192.168.2.1 \
Nameserver=192.168.1.116 \
Searchdns=example.com \
InstNetDev=osa; \
Netmask=255.255.255.0 \
Broadcast=192.168.2.255 \
OsaInterface=qdio \
Layer2=0 \
PortNo=0 \
ReadChannel=0.0.0700 \
WriteChannel=0.0.0701 \
DataChannel=0.0.0702 \
DASD=600"

4.2.1.4 Installing from DVD or Flash Disk of the HMC

To install SUSE Linux Enterprise Server on IBM z Systems servers, usually a network installation source is needed. However, in certain environments, it could occur that this requirement cannot be fulfilled. With SUSE Linux Enterprise Server, you can use the existing DVD or the flash disk of the Hardware Management Console (HMC) as an installation source for installation on an LPAR.

To install from the media in the DVD or the flash disk of the HMC, proceed as follows:

Important
Important: Configure Network

Do not forget to configure the network in linuxrc before starting the installation. There is no way to pass on boot parameters later in time, and it is very likely that you will need network access. In linuxrc, go to Start Installation, then choose Network Setup.

Important
Important: Linux System Must Boot First

Before granting access to the media in the DVD or the flash disk of the HMC, wait until the Linux system is booting. IPLing can disrupt the connection between the HMC and the LPAR. If the first attempt to use the described method fails, you can grant the access and retry the option HMC.

Note
Note: Installation Repository

Because of the transitory nature of the assignment, the DVD or the flash disk files will not be kept as a repository for installation. If you need an installation repository, register and use the online repository.

4.2.2 Installation Types

This section provides information about which steps must be performed to install SUSE Linux Enterprise Server for each of the installation modes and where to find the appropriate information. When the preparation steps described in the previous chapters have been completed, follow the installation overview of the desired installation mode to install SUSE Linux Enterprise Server on your system.

As described in Section 4.2.1, “Making the Installation Data Available”, there are three different installation modes for Linux on IBM z Systems:

  • LPAR installation

  • z/VM installation

  • KVM guest installation

Procedure 4.1: Overview of an LPAR Installation
  1. Prepare the devices needed for installation. See Section 4.2.3.1, “Preparing the IPL of an LPAR Installation”.

  2. IPL the installation system. See Section 4.2.4.1, “IPLing an LPAR Installation”.

  3. Configure the network. See Section 4.2.5, “Network Configuration”.

  4. Connect to the SUSE Linux Enterprise Server installation system. See Section 4.2.6, “Connecting to the SUSE Linux Enterprise Server Installation System”.

  5. Start the installation using YaST and IPL the installed system. See Chapter 6, Installation with YaST.

Procedure 4.2: Installation Overview of z/VM Installation
  1. Prepare the devices needed for installation. See Section 4.2.3.2, “Preparing the IPL of a z/VM Installation”.

  2. IPL the installation system. See Section 4.2.4.2, “IPLing a z/VM Installation”.

  3. Configure the network. See Section 4.2.5, “Network Configuration”.

  4. Connect to the SUSE Linux Enterprise Server installation system. See Section 4.2.6, “Connecting to the SUSE Linux Enterprise Server Installation System”.

  5. Start the installation using YaST and IPL the installed system. See Chapter 6, Installation with YaST.

Procedure 4.3: Overview of a KVM Guest Installation
  1. Create a virtual disk image and write a domain XML file. See Section 4.2.3.3, “Preparing the IPL of a KVM Guest Installation”.

  2. Prepare the installation target and IPL the VM Guest. See Section 4.2.4.3, “IPLing a KVM Guest Installation”.

  3. Section 4.2.5.3, “Set Up the Network and Select the Installation Source”.

  4. Connect to the SUSE Linux Enterprise Server installation system. See Section 4.2.6, “Connecting to the SUSE Linux Enterprise Server Installation System”.

  5. Start the installation using YaST and IPL the installed system. See Chapter 6, Installation with YaST.

4.2.3 Preparing the IPL of the SUSE Linux Enterprise Server Installation System

4.2.3.1 Preparing the IPL of an LPAR Installation

Configure your IBM z Systems system to start in ESA/S390 or Linux-only mode with an appropriate activation profile and IOCDS. Consult IBM documentation for more on how to achieve this. Proceed with Section 4.2.4.1, “IPLing an LPAR Installation”.

4.2.3.2 Preparing the IPL of a z/VM Installation

4.2.3.2.1 Adding a Linux Guest

The first step is to attach and format one or multiple DASDs in the system to be used by the Linux guest in z/VM. Next, create a new user in z/VM. The example shows the directory for a user LINUX1 with the password LINPWD, 1 GB of memory (extendable up to 2 GB), 32 MB of expanded RAM (XSTORE), several minidisks (MDISK), two CPUs, and an OSA QDIO device.

Tip
Tip: Assigning Memory to z/VM guests

When assigning memory to a z/VM guest, make sure that the memory size suits the needs of your preferred installation type. See Section 4.1.1.1.1, “Memory Requirements”. To set the memory size to 1 GB, use the command CP DEFINE STORAGE 1G. After the installation has finished, reset the memory size to the desired value.

Example 4.1: Configuration of a z/VM Directory
USER LINUX1 LINPWD 1024M 2048M G
*____________________________________________
* LINUX1
*____________________________________________
* This VM Linux guest has two CPUs defined.

CPU 01 CPUID 111111
CPU 02 CPUID 111222
IPL CMS PARM AUTOCR
IUCV ANY
IUCV ALLOW
MACH ESA 10
OPTION MAINTCCW RMCHINFO
SHARE RELATIVE 2000
CONSOLE 01C0 3270 A
SPOOL 000C 2540 READER *
SPOOL 000D 2540 PUNCH A
SPOOL 000E 3203 A
* OSA QDIO DEVICE DEFINITIONS
DEDICATE 9A0 9A0
DEDICATE 9A1 9A1
DEDICATE 9A2 9A2
*
LINK MAINT 0190 0190 RR
LINK MAINT 019E 019E RR
LINK MAINT 019D 019D RR
* MINIDISK DEFINITIONS
MDISK 201 3390 0001 0050 DASD40 MR ONE4ME TWO4ME THR4ME
MDISK 150 3390 0052 0200 DASD40 MR ONE4ME TWO4ME THR4ME
MDISK 151 3390 0253 2800 DASD40 MR ONE4ME TWO4ME THR4ME

This example uses minidisk 201 as the guest's home disk. Minidisk 150 with 200 cylinders is the Linux swap device. Disk 151 with 2800 cylinders holds the Linux installation.

Now add (as the user MAINT) the guest to the user directory with DIRM FOR LINUX1 ADD. Enter the name of the guest (LINUX1) and press F5. Set up the environment of the user with:

DIRM DIRECT
DIRM USER WITHPASS

The last command returns a reader file number. This number is needed for the next command:

RECEIVE <number> USER DIRECT A (REPL)

You can now log in on the guest as user LINUX1.

If you do not have the dirmaint option available, refer to the IBM documentation to set up this user.

Proceed with Section 4.2.4.2, “IPLing a z/VM Installation”.

4.2.3.3 Preparing the IPL of a KVM Guest Installation

A KVM guest installation requires a domain XML file defining the virtual machine and at least one virtual disk image for the installation.

4.2.3.3.1 Create a Virtual Disk Image

By default libvirt searches for disk images in /var/lib/libvirt/images/ on the VM Host Server. Although images can also be stored anywhere on the file system, it is recommended to store all images in a single location for easier maintainability. The following example creates a qcow2 image with a size of 10 GB in /var/lib/libvirt/images/. For more information refer to Section 28.2, “Managing Disk Images with qemu-img.

  1. Log in to the KVM host server.

  2. Run the following command to create the image:

    qemu-img create -f qcow2 /var/lib/libvirt/images/s12lin_qcow2.img 10G
4.2.3.3.2 Write a Domain XML File

A domain XML file is used to define the VM Guest. To create the domain XML file open an empty file s12-1.xml with an editor and create a file like in the following example.

Example 4.2: Example Domain XML File

The following example creates a VM Guest with a single CPU, 1 GB RAM, and the virtual disk image created in the previous section (Section 4.2.3.3.1, “Create a Virtual Disk Image”). It assumes that the host network interface to which the virtual server is attached is bond0. Change the source devices element to match your network setup.

<domain type="kvm">
 <name>s12-1</name>
 <description>Guest-System SUSE Sles12</description>
 <memory>1048576</memory>
 <vcpu>1</vcpu>
 <os>
  <type arch="s390x" machine="s390-ccw-virtio">hvm</type>
  <!-- Boot kernel - remove 3 lines after successfull installation -->
  <kernel>/var/lib/libvirt/images/s12-kernel.boot</kernel>
  <initrd>/var/lib/libvirt/images/s12-initrd.boot</initrd>
  <cmdline>linuxrcstderr=/dev/console</cmdline>
 </os>
 <iothreads>1</iothreads>
 <on_poweroff>destroy</on_poweroff>
 <on_reboot>restart</on_reboot>
 <on_crash>preserve</on_crash>
 <devices>
  <emulator>/usr/bin/qemu-system-s390x</emulator>
  <disk type="file" device="disk">
   <driver name="qemu" type="qcow2" cache="none" iothread="1" io="native"/>
   <source file="/var/lib/libvirt/images/s12lin_qcow2.img"/>
   <target dev="vda" bus="virtio"/>
  </disk>
  <interface type="direct">
   <source dev="bond0" mode="bridge"/>
   <model type="virtio"/>
  </interface>
  <console type="pty">
   <target type="sclp"/>
  </console>
 </devices>
</domain>

4.2.4 IPLing the SUSE Linux Enterprise Server Installation System

4.2.4.1 IPLing an LPAR Installation

There are different ways to IPL SUSE Linux Enterprise Server into an LPAR. The preferred way is to use the Load from CD-ROM or server feature of the SE or HMC.

4.2.4.1.1 IPL from DVD-ROM

Mark the LPAR to install and select Load from CD-ROM or server. Leave the field for the file location blank or enter the path to the root directory of the first DVD-ROM and select continue. In the list of options that appears, select the default selection. Operating system messages should now show the kernel boot messages.

4.2.4.1.2 IPL from FCP-Attached SCSI DVD

You can use the Load procedure by selecting SCSI as Load type to IPL from SCSI. Enter the WWPN (Worldwide port name) and LUN Logical unit number) provided by your SCSI bridge or storage (16 digits—do not omit the trailing 0s). The boot program selector must be 2. Use your FCP adapter as Load address and perform an IPL.

4.2.4.2 IPLing a z/VM Installation

This section is about IPLing the installation system to install SUSE Linux Enterprise Server for IBM z Systems on a z/VM system.

4.2.4.2.1 IPL from the z/VM Reader

You need a working TCP/IP connection and an FTP client program within your newly defined z/VM guest to transfer the installation system via FTP. Setting up TCP/IP for z/VM is beyond the scope of this manual. Refer to the appropriate IBM documentation.

Log in as the z/VM Linux guest to IPL. Make the content of the directory /boot/s390x on DVD 1 of the SUSE Linux Enterprise Server for IBM z Systems available via FTP within your network. From this directory, get the files linux, initrd, parmfile, and sles12.exec. Transfer the files with a fixed block size of 80 characters. Specify it with the FTP command locsite fix 80. It is important to copy linux (the Linux kernel) and initrd (the installation image) as binary files, so use the binary transfer mode. parmfile and sles12.exec need to be transferred in ASCII mode.

The example shows the steps necessary. In this example, the required files are accessible from an FTP server at the IP address 192.168.0.3 and the login is lininst. It may differ for your network.

Example 4.3: Transferring the Binaries via FTP
FTP 192.168.0.3
VM TCP/IP FTP Level 530
Connecting to 192.168.0.3, port 21
220 ftpserver FTP server (Version wu-2.4.2-academ[BETA-18](1)
Thu Feb 11 16:09:02 GMT 2010) ready.
USER
lininst
331 Password required for lininst
PASS
******
230 User lininst logged in.
Command:
binary
200 Type set to I
Command:
locsite fix 80
Command:
get /media/dvd1/boot/s390x/linux sles12.linux
200 PORT Command successful
150 Opening BINARY mode data connection for /media/dvd1/boot/s390x/linux
(10664192 bytes)
226 Transfer complete.
10664192 bytes transferred in 13.91 seconds.
Transfer rate 766.70 Kbytes/sec.
Command:
get /media/dvd1/boot/s390x/initrd sles12.initrd
200 PORT Command successful
150 Opening BINARY mode data connection for /media/dvd1/boot/s390x/initrd
(21403276 bytes)
226 Transfer complete.
21403276 bytes transferred in 27.916 seconds.
Transfer rate 766.70 Kbytes/sec.
Command:
ascii
200 Type set to A
Command:
get /media/dvd1/boot/s390x/parmfile sles12.parmfile
150 Opening ASCII mode data connection for /media/dvd1/boot/s390x/parmfile
(5 bytes)
226 Transfer complete.
5 bytes transferred in 0.092 seconds.
Transfer rate 0.05 Kbytes/sec.
Command:
get /media/dvd1/boot/s390x/sles12.exec sles12.exec
150 Opening ASCII mode data connection for /media/dvd1/boot/s390x/sles12.exec
(891 bytes)
226 Transfer complete.
891 bytes transferred in 0.097 seconds.
Transfer rate 0.89 Kbytes/sec.
Command:
quit

Use the REXX script sles12.exec you downloaded to IPL the Linux installation system. This script loads the kernel, parmfile, and the initial RAM disk into the reader for IPL.

Example 4.4: SLES12 EXEC
/* REXX LOAD EXEC FOR SUSE LINUX S/390 VM GUESTS       */
/* LOADS SUSE LINUX S/390 FILES INTO READER            */
SAY ''
SAY 'LOADING SLES12 FILES INTO READER...'
'CP CLOSE RDR'
'PURGE RDR ALL'
'SPOOL PUNCH * RDR'
'PUNCH SLES12 LINUX A (NOH'
'PUNCH SLES12 PARMFILE A (NOH'
'PUNCH SLES12 INITRD A (NOH'
'IPL 00C'

With this script you can IPL the SUSE Linux Enterprise Server installation system with the command sles12. The Linux kernel then starts and prints its boot messages.

To continue the installation, proceed to Section 4.2.5, “Network Configuration”.

4.2.4.2.2 IPL from FCP-Attached SCSI DVD

To IPL in z/VM, prepare the SCSI IPL process by using the SET LOADDEV parameter:

SET LOADDEV PORTNAME 200400E8 00D74E00 LUN 00020000 00000000 BOOT 2

After setting the LOADDEV parameter with the appropriate values, IPL your FCP adapter, for example:

IPL FC00

To continue the installation, proceed with Section 4.2.5, “Network Configuration”.

4.2.4.2.3 IPL from a Cobbler Server with zPXE

To IPL from a Cobbler server with zPXE you need to transfer the zpxe.rexx script via FTP from the Cobbler server to your z/VM guest. The z/VM guest needs a working TCP/IP connection and an FTP client program.

Log in as the z/VM Linux guest to IPL and transfer the script with a fixed size of 80 characters in ASCII mode (see Example 4.3, “Transferring the Binaries via FTP” for an example). The zpxe.rexx script is available on the Cobbler server at /usr/share/doc/packages/s390-tools/.

zpxe.rexx is supposed to replace the PROFILE EXEC of your guest. Make a backup copy of the existing PROFILE EXEC and rename ZPXE REXX to PROFILE EXEC. Alternatively call ZPXE REXX from the existing PROFILE EXEC by using a new line with the following content: 'ZPXE REXX'.

The last step is to create a configuration file, ZPXE CONF, telling ZPXE REXX which Cobbler server to contact and which disk to IPL. Run xedit zpxe conf a and create ZPXE CONF with the following content (replace the example data accordingly):

HOST cobbler.example.com
IPLDISK 600

On the next login to your z/VM guest, the Cobbler server will be connected. If an installation is scheduled on the Cobbler server, it will be executed. To schedule the installation, run the following command on the Cobbler server:

cobbler system edit --name ID1 --netboot-enabled 12 --profile PROFILENAME3

1

z/VM user ID.

2

Enable IPLing from the network.

3

Name of an existing profile, see Section 4.2.1.3.3, “Adjusting the Profile”.

4.2.4.3 IPLing a KVM Guest Installation

To start the guest installation, you first need to start the VM Guest defined in Section 4.2.3.3.1, “Create a Virtual Disk Image”. A prerequisite for this is to first make the kernel and initrd required for IPLing available.

4.2.4.3.1 Preparing the installation source

Kernel and initrd of the installation system need to be copied to the VM Host Server to be able to IPL the VM Guest into the installation system.

  1. Log in to the KVM host and make sure you can connect to the remote host or device serving the installation source.

  2. Copy the following two files from the installation source to /var/lib/libvirt/images/. If the data is served from a remote host, use ftp, sftp, or scp to transfer the files:

    /boot/s390x/initrd
    /boot/s390x/cd.ikr
  3. Rename the files on the KVM host:

    cd /var/lib/libvirt/images/
    mv initrd s12-initrd.boot
     mv cd.ikr s12-kernel.boot
4.2.4.3.2 IPL the VM Guest

To IPL the VM Guest, log in to the KVM host and run the following command:

virsh  create s12-1.xml --console

After the start-up of the VM Guest has completed, the installation system starts and you will see the following message:

Domain s12-1 started
Connected to domain s12-1
Escape character is ^]
Initializing cgroup subsys cpuset
Initializing cgroup subsys cpu
Initializing
cgroup subsys cpuacct
.
.
Please make sure your installation medium is available.
Retry?
0) <-- Back <--
1) Yes
2) No

Answer 2) No and choose Installation on the next step. Proceed as described in Section 4.2.5.3, “Set Up the Network and Select the Installation Source”.

4.2.5 Network Configuration

Wait until the kernel has completed its start-up routines. If you are installing in basic mode or in an LPAR, open the Operating System Messages on the HMC or SE.

First, choose Start Installation in the linuxrc main menu then Start Installation or Update to start the installation process. Select Network as your installation medium then select the type of network protocol you will be using for the installation. Section 4.2.1, “Making the Installation Data Available” describes how to make the installation data available for the various types of network connections. Currently, FTP, HTTP, NFS, and SMB/CIFS (Windows file sharing) are supported.

Now choose an OSA or HiperSockets network device over which to receive the installation data from the list of available devices. The list may also contain CTC, ESCON, or IUCV devices, but they are no longer supported on SUSE Linux Enterprise Server.

4.2.5.1 Configure a HiperSockets Interface

Select a Hipersocket device from the list of network devices. Then enter the numbers for the read, write and data channels:

Example 4.5: Supported Network Connection Types and Driver Parameters
Choose the network device.

 1) IBM parallel CTC Adapter (0.0.0600)
 2) IBM parallel CTC Adapter (0.0.0601)
 3) IBM parallel CTC Adapter (0.0.0602)
 4) IBM Hipersocket (0.0.0800)
 5) IBM Hipersocket (0.0.0801)
 6) IBM Hipersocket (0.0.0802)
 7) IBM OSA Express Network card (0.0.0700)
 8) IBM OSA Express Network card (0.0.0701)
 9) IBM OSA Express Network card (0.0.0702)
10) IBM OSA Express Network card (0.0.f400)
11) IBM OSA Express Network card (0.0.f401)
12) IBM OSA Express Network card (0.0.f402)
13) IBM IUCV

> 4

Device address for read channel. (Enter '+++' to abort).
[0.0.800]> 0.0.800

Device address for write channel. (Enter '+++' to abort).
[0.0.801]> 0.0.801

Device address for data channel. (Enter '+++' to abort).
[0.0.802]> 0.0.802

4.2.5.2 Configure an OSA Express Device

Select an OSA Express device from the list of network devices and provide a port number. Then enter the numbers for the read, write and data channels and the port name, if applicable. Choose whether to enable OSI Layer 2 support.

The port number was added to support the new 2 port OSA Express 3 Network devices. If you are not using an OSA Express 3 device, enter 0. OSA Express cards also have the option of running in an OSI layer 2 support mode or using the older more common layer 3 mode. The card mode affects all systems that share the device including systems on other LPARs. If in doubt, specify 2 for compatibility with the default mode used by other operating systems such as z/VM and z/OS. Consult with your hardware administrator for further information on these options.

Example 4.6: Network Device Driver Parameters
Choose the network device.

 1) IBM parallel CTC Adapter (0.0.0600)
 2) IBM parallel CTC Adapter (0.0.0601)
 3) IBM parallel CTC Adapter (0.0.0602)
 4) IBM Hipersocket (0.0.0800)
 5) IBM Hipersocket (0.0.0801)
 6) IBM Hipersocket (0.0.0802)
 7) IBM OSA Express Network card (0.0.0700)
 8) IBM OSA Express Network card (0.0.0701)
 9) IBM OSA Express Network card (0.0.0702)
10) IBM OSA Express Network card (0.0.f400)
11) IBM OSA Express Network card (0.0.f401)
12) IBM OSA Express Network card (0.0.f402)
13) IBM IUCV

> 7

Enter the relative port number. (Enter '+++' to abort).
> 0

Device address for read channel. (Enter '+++' to abort).
[0.0.0700]> 0.0.0700

Device address for write channel. (Enter '+++' to abort).
[0.0.0701]> 0.0.0701

Device address for data channel. (Enter '+++' to abort).
[0.0.0702]> 0.0.0702

Enable OSI Layer 2 support?

0) <-- Back <--
1) Yes
2) No

> 1

MAC address. (Enter '+++' to abort).
> +++

4.2.5.3 Set Up the Network and Select the Installation Source

When all network device parameters have been entered, the respective driver is installed and you see the corresponding kernel messages.

Next, decide whether to use DHCP autoconfiguration for setting up the network interface parameters. Because DHCP only works on a few devices and requires special hardware configuration settings, you probably want to say NO here. When you do so, you are prompted for the following networking parameters:

  • The IP address of the system to install

  • The corresponding netmask (if not having been specified with the IP address)

  • The IP address of a gateway to reach the server

  • A list of search domains covered by the domain name server (DNS)

  • The IP address of your domain name server

Example 4.7: Networking Parameters
Automatic configuration via DHCP?

0) <-- Back <--
1) Yes
2) No

> 2

Enter your IP address with network prefix.

You can enter more than one, separated by space, if necessary.
Leave empty for autoconfig.

Examples: 192.168.5.77/24 2001:db8:75:fff::3/64. (Enter '+++' to abort).
> 192.168.0.20/24

Enter your name server IP address.

You can enter more than one, separated by space, if necessary.
Leave empty if you don't need one.

Examples: 192.168.5.77 2001:db8:75:fff::3. (Enter '+++' to abort).
> 192.168.0.1

Enter your search domains, separated by a space:. (Enter '+++' to abort).
> example.com

Enter the IP address of your name server. Leave empty if you do not need one. (En
ter '+++' to abort).
> 192.168.0.1

Finally, you are prompted for details on the installation server, such as the IP address, the directory containing the installation data, and login credentials. Once all required data is entered, the installation system loads.

4.2.6 Connecting to the SUSE Linux Enterprise Server Installation System

After having loaded the installation system, linuxrc wants to know what type of display you want to use to control the installation procedure. Possible choices are X11 (X Window System), VNC (Virtual Network Computing protocol), SSH (text mode or X11 installation via Secure Shell), or ASCII Console. Selecting VNC or SSH is recommended.

When selecting the latter (ASCII Console), YaST will be started in text mode and you can perform the installation directly within your terminal. See Chapter 5, YaST in Text Mode for instructions on how to use YaST in text mode. Using the ASCII Console is only useful when installing into LPAR.

Note
Note: Terminal Emulation for ASCII Console

To be able to work with YaST in text mode, it needs to run in a terminal with VT220/Linux emulation (also called ASCII console). You cannot use YaST in a 3270 terminal, for example.

4.2.6.1 Initiating the Installation for VNC

  1. After the installation option VNC has been chosen, the VNC server starts. A short note displayed in the console provides information about which IP address and display number is needed for a connection with vncviewer.

  2. Start a VNC client application on your client system.

  3. Enter the IP address and the display number of the SUSE Linux Enterprise Server installation system when prompted to do so.

  4. After the connection has been established, start installing SUSE Linux Enterprise Server with YaST.

4.2.6.2 Initiating the Installation for the X Window System

Important
Important: X Authentication Mechanism

The direct installation with the X Window System relies on a primitive authentication mechanism based on host names. This mechanism is disabled on current SUSE Linux Enterprise Server versions. Installation with SSH or VNC is preferred.

  1. Make sure that the X server allows the client (the system that is installed) to connect. Set the variable DISPLAYMANAGER_XSERVER_TCP_PORT_6000_OPEN="yes" in the file /etc/sysconfig/displaymanager. Then restart the X server and allow client binding to the server using xhost <client IP address>.

  2. When prompted at the installation system, enter the IP address of the machine running the X server.

  3. Wait until YaST opens then start the installation.

4.2.6.3 Initiating the Installation for SSH

To connect to an installation system with the name earth using SSH, execute ssh -X earth. If your workstation runs on Microsoft Windows, use the SSH and telnet client and terminal emulator Putty which is available from http://www.chiark.greenend.org.uk/~sgtatham/putty/. Set Enable X11 forwarding in Putty under Connection › SSH › X11. If you use another operating system, execute ssh -X earth to connect to an installation system with the name earth. X-Forwarding over SSH is supported if you have a local X server available. Otherwise, YaST provides a text interface over ncurses.

A login prompt appears. Enter root and log in with your password. Enter yast.ssh to start YaST. YaST then guides you through the installation.

Proceed with the detailed description of the installation procedure that can be found in Chapter 6, Installation with YaST.

4.2.7 The SUSE Linux Enterprise Server Boot Procedure on IBM z Systems

The boot process for SLES 10 and 11 followed the scheme provided below. For in-depth information refer to the documentation provided at http://www.ibm.com/developerworks/linux/linux390/documentation_suse.html.

  1. Provide the kernel.

  2. Provide or create an initrd for the given kernel.

  3. Provide the correct paths for the initrd and the kernel in /etc/zipl.conf.

  4. Install the configuration provided by /etc/zipl.conf to the system.

With SLES 12 the way SUSE Linux Enterprise Server is booted on IBM z Systems has changed. Several reasons led to this change:

  • Alignment with other architectures: From an administrative point of view SLES systems should behave the same on all architectures.

  • Btrfs: The zipl boot loader is technically incompatible with Btrfs, the new default root file system for SLES (see Section 1.2, “Btrfs” for details).

  • Support for system rollbacks with Snapper: Snapper, in combination with Btrfs, provides bootable system snapshots which can be used for system rollbacks (see Chapter 7, System Recovery and Snapshot Management with Snapper for details).

For those reasons, starting with SLES 12, GRUB 2 replaces zipl on IBM SUSE Linux Enterprise Server for z Systems. GRUB 2 on the AMD64/Intel 64 architecture includes device drivers on the firmware level to access the file system. On the mainframe there is no firmware and adding ccw to GRUB 2 would not only be a major undertaking, but would also require a reimplementation of zipl in GRUB 2. Therefore SUSE Linux Enterprise Server uses a two-stage approach:

Stage One:

A separate partition containing the kernel and an initrd is mounted to /boot/zipl (somewhat similar to /boot/efi on UEFI platforms). This kernel and the initrd are loaded via zipl using the configuration from /boot/zipl/config.

This configuration adds the keyword initgrub to the kernel command line. When the kernel and initrd are loaded, the initrd activates the devices required to mount the root file system (see /boot/zipl/active_devices.txt). Afterward a GRUB 2 user space program is started, which reads /boot/grub2/grub.cfg.

Stage Two:

The kernel and the initrd specified in /boot/grub2/grub.cfg are started via kexec. All devices listed in /boot/zipl/active_devices.txt are activated, the root file system is mounted and the boot procedure continues like on the other architectures.

4.3 The parmfile—Automating the System Configuration

The installation process can be partly automated by specifying the crucial parameters in the parmfile. The parmfile contains all the data required for network setup and DASD configuration. In addition to that, it can be used to set up the connection method to the SUSE Linux Enterprise Server installation system and the YaST instance running there. User interaction is thus limited to the actual YaST installation controlled by YaST dialogs.

The following parameters can be passed to the installation routine, which takes them as default values for installation. All IP addresses, server names, and numerical values are examples. Replace these values with the ones needed in your installation scenario.

The number of lines in the parmfile is limited to 10. Specify more than one parameter on a line. Parameter names are not case-sensitive. Separate the parameters by spaces. You may specify the parameters in any order. Always keep the PARAMETER=value string together in one line. For example:

Hostname=s390zvm01.suse.de HostIP=10.11.134.65
Tip
Tip: Using IPv6 during the Installation

By default you can only assign IPv4 network addresses to your machine. To enable IPv6 during installation, enter one of the following parameters at the boot prompt: ipv6=1 (accept IPv4 and IPv6) or ipv6only=1 (accept IPv6 only).

Some of the following parameters are required. If they are missing, the automatic process pauses and asks you to enter the value manually.

4.3.1 General Parameters

AutoYaST=<URL> Manual=0

The AutoYaST parameter specifies the location of the autoinst.xml control file for automatic installation. The Manual parameter controls if the other parameters are only default values that still must be acknowledged by the user. Set this parameter to 0 if all values should be accepted and no questions asked. Setting AutoYaST implies setting Manual to 0.

Info=<URL>

Specifies a location for a file from which to read additional options. This helps to overcome the limitations of 10 lines (and 80 characters per line under z/VM) for the parmfile. More documentation on the Info file can be found in Section 6.3.3, “Combining the linuxrc info file with the AutoYaST control file”. Since the Info file can typically only be accessed through the network on z Systems, you cannot use it to specify options required to set up the network (these options described in Section 4.3.2, “Configuring the Network Interface”). Also other linuxrc specific options such as for debugging need to be specified in the parmfile to be effective.

Upgrade=<0|1>

To upgrade your SUSE Linux Enterprise, specify Upgrade=1. Therefore, a custom parmfile is required for upgrading an existing installation of SUSE Linux Enterprise. Without this parameter, the installation provides no upgrade option.

4.3.2 Configuring the Network Interface

Important
Important: Configuring the Network Interface

The settings discussed in this section apply only to the network interface used during installation. Configure additional network interfaces in the installed system by following the instructions given in Section 16.5, “Configuring a Network Connection Manually”.

Hostname=zsystems.example.com

Enter the fully qualified host name.

Domain=example.com

Domain search path for DNS. Allows you to use short host names instead of fully qualified ones.

HostIP=192.168.1.2

Enter the IP address of the interface to configure.

Gateway=192.168.1.3

Specify the gateway to use.

Nameserver=192.168.1.4

Specify the DNS server in charge.

InstNetDev=osa

Enter the type of interface to configure. Possible values are osa, hsi, ctc, escon, and iucv (CTC, ESCON, and IUCV are no longer officially supported).

For the interfaces of type hsi and osa, specify an appropriate netmask and an optional broadcast address:

Netmask=255.255.255.0
Broadcast=192.168.255.255

For the interfaces of type ctc, escon, and iucv (CTC, ESCON, and IUCV are no longer officially supported), enter the IP address of the peer:

Pointopoint=192.168.55.20
OsaInterface=<lcs|qdio>

For osa network devices, specify the host interface (qdio or lcs).

Layer2=<0|1>

For osa QDIO Ethernet and hsi devices, specify whether to enable (1) or disable (0) OSI Layer 2 support.

OSAHWAddr=02:00:65:00:01:09

For Layer 2-enabled osa QDIO Ethernet devices. Either specify a MAC address manually or state OSAHWADDR= (with trailing white space) for the system default.

PortNo=<0|1>

For osa network devices, specify the port number (provided the device supports this feature). The default value is 0.

Each of the interfaces requires certain setup options:

  • Interfaces ctc and escon (CTC and ESCON are no longer officially supported):

    ReadChannel=0.0.0600
    WriteChannel=0.0.0601

    ReadChannel specifies the READ channel to use. WriteChannel specifies the WRITE channel.

  • For the ctc interface (no longer officially supported), specify the protocol that should be used for this interface:

    CTCProtocol=<0/1/2>

    Valid entries would be:

    0

    Compatibility mode, also for non-Linux peers other than OS/390 and z/OS (this is the default mode)

    1

    Extended mode

    2

    Compatibility mode with OS/390 and z/OS

  • Network device type osa with interface lcs:

    ReadChannel=0.0.0124

    ReadChannel stands for the channel number used in this setup. A second port number can be derived from this by adding one to ReadChannel. Portnumber is used to specify the relative port.

  • Interface iucv:

    IUCVPeer=PEER

    Enter the name of the peer machine.

  • Network device type osa with interface qdio for OSA-Express Gigabit Ethernet:

    ReadChannel=0.0.0700
    WriteChannel=0.0.0701
    DataChannel=0.0.0702

    For ReadChannel, enter the number of the READ channel. For WriteChannel, enter the number of the WRITE channel. DataChannel specifies the DATA channel. Make sure that the READ channel carries an even device number.

  • Interface hsi for HiperSockets and VM guest LANs:

    ReadChannel=0.0.0800
    WriteChannel=0.0.0801
    DataChannel=0.0.0802

    For ReadChannel, enter the appropriate number for the READ channel. For WriteChannel and DataChannel, enter the WRITE and DATA channel numbers.

4.3.3 Specifying the Installation Source and YaST Interface

Install=nfs://server/directory/DVD1/

Specify the location of the installation source to use. Possible protocols are nfs, smb (Samba/CIFS), ftp, tftp http, and https.

If an ftp, tftp or smb URL is given, specify the user name and password with the URL. These parameters are optional and anonymous or guest login is assumed if they are not given.

Install=ftp://USER:PASSWORD@SERVER/DIRECTORY/DVD1/
Install=tftp://USER:PASSWORD@SERVER/DIRECTORY/DVD1/

If you want to install over an encrypted connection, use an https URL. If the certificate cannot be verified, use the sslcerts=0 boot option to disable certificate checking.

In case of a Samba or CIFS installation, you can also specify the domain that should be used:

Install=smb://WORKDOMAIN;USER:PASSWORD@SERVER/DIRECTORY/DVD1/
ssh=1 vnc=1 Display_IP=192.168.42.42

Depending on which parameter you give, a remote X server, SSH, or VNC will be used for installation. ssh enables SSH installation, vnc starts a VNC server on the installing machine, and Display_IP causes the installing system to try to connect to an X server at the given address. Only one of these parameters should be set at any time.

Important
Important: X Authentication Mechanism

The direct installation with the X Window System relies on a primitive authentication mechanism based on host names. This mechanism is disabled on current SUSE Linux Enterprise Server versions. Installation with SSH or VNC is preferred.

To allow a connection between YaST and the remote X server, run xhost <IP address> with the address of the installing machine on the remote machine.

For VNC, specify a password of six to eight characters to use for installation:

VNCPassword=<a password>

For SSH, specify a password of six to eight characters to use for installation:

ssh.password=<a password>

4.3.4 Example Parmfiles

The maximum capacity of a parmfile is 860 characters. As a rule of thumb, the parmfile should contain a maximum of 10 lines with no more than 79 characters. When reading a parmfile, all lines are concatenated without adding white spaces, therefore the last character (79) of each line needs to be a Space.

To receive potential error messages on the console, use

linuxrclog=/dev/console
Example 4.8: Parmfile for an Installation from NFS with VNC and AutoYaST
ramdisk_size=131072 root=/dev/ram1 ro init=/linuxrc TERM=dumb
instnetdev=osa osainterface=qdio layer2=1 osahwaddr=
pointopoint=192.168.0.1
hostip=192.168.0.2
nameserver=192.168.0.3
install=nfs://192.168.0.4/SLES/SLES-12-Server/s390x/DVD1
autoyast=http://192.168.0.5/autoinst.xml
linuxrclog=/dev/console vnc=1
VNCPassword=testing
Example 4.9: Parmfile for Installation with NFS, SSH, and HSI and AutoYaST with NFS
ramdisk_size=131072 root=/dev/ram1 ro init=/linuxrc TERM=dumb
AutoYast=nfs://192.168.1.1/autoinst/s390.xml
Hostname=zsystems.example.com HostIP=192.168.1.2
Gateway=192.168.1.3 Nameserver=192.168.1.4
InstNetDev=hsi layer2=0
Netmask=255.255.255.128 Broadcast=192.168.1.255
readchannel=0.0.702c writechannel=0.0.702d datachannel=0.0.702e
install=nfs://192.168.1.5/SLES-12-Server/s390x/DVD1/
ssh=1 ssh.password=testing linuxrclog=/dev/console

4.4 Using the vt220 Terminal Emulator

Recent MicroCode Levels allow the use of an integrated vt220 terminal emulator (ASCII terminal) in addition to the standard line mode terminal. The vt220 terminal is connected to /dev/ttysclp0. The line mode terminal is connected to /dev/ttysclp_line0. For LPAR installations, the vt220 terminal emulator is activated by default.

To start the ASCII console on HMC, log in to the HMC, and select Systems Management › Systems › IMAGE_ID . Select the radio button for the LPAR and select Recovery › Integrated ASCII Console.

To redirect the kernel messages at boot time from the system console to the vt220 terminal, add the following entries to the parameters line in /etc/zipl.conf:

console=ttysclp0 console=ttysclp_line0

The resulting parameters line would look like the following example:

parameters = "root=/dev/dasda2 TERM=dumb console=ttysclp0 console=ttysclp_line0"

Save the changes in /etc/zipl.conf, run zipl, and reboot the system.

4.5 Further In-Depth Information about IBM z Systems

Find additional in-depth technical documentation about IBM z Systems in the IBM Redbooks (https://www.redbooks.ibm.com/Redbooks.nsf/domains/zsystems) or at IBM developerWorks (https://www.ibm.com/developerworks/linux/linux390/). SUSE Linux Enterprise Server-specific documentation is available from https://www.ibm.com/developerworks/linux/linux390/documentation_suse.html.

4.5.1 General Documents about Linux on IBM z Systems

A general coverage of Linux on IBM z Systems can be found in the following documents:

  • Linux on IBM eServer zSeries and S/390: ISP and ASP Solutions (SG24-6299)

These documents might not reflect the current state of Linux, but the principles of Linux deployment outlined there remain accurate.

4.5.2 Technical Issues of Linux on IBM z Systems

Refer to the following documents to get in-depth technical information about the Linux kernel and application topics. Refer to the Internet for up-to-date versions of these documents for the most recent code drop (http://www.ibm.com/developerworks/linux/linux390/index.html).

  • Linux on System z Device Drivers, Features, and Commands

  • zSeries ELF Application Binary Interface Supplement

  • Linux on System z Device Drivers, Using the Dump Tools

  • IBM zEnterprise 196 Technical Guide

  • IBM zEnterprise EC12 Technical Guide

  • IBM z13 Technical Guide

There also is a Redbook for Linux application development at http://www.redbooks.ibm.com:

  • Linux on IBM eServer zSeries and S/390: Application Development (SG24-6807)

4.5.3 Advanced Configurations for Linux on IBM z Systems

Refer to the following Redbooks, Redpapers, and links for some more complex IBM z Systems scenarios:

4.5.4 Virtualization with KVM on IBM z Systems

Refer to the following documents at https://www.ibm.com/developerworks/linux/linux390/documentation_dev.html for more information on KVM on IBM z Systems:

  • Installing SUSE Linux Enterprise Server 12 as a KVM Guest (SC34-2755-00)

  • KVM Virtual Server Quick Start (SC34-2753-01)

  • KVM Virtual Server Management (SC34-2752-01)

  • Device Drivers, Features, and Commands for Linux as a KVM Guest (Kernel 4.4) (SC34-2754-01)

5 Installation on ARM AArch64

  • Filename: deployment_prep_aarch64.xml
  • ID: cha.aarch64
Abstract

This chapter describes the steps necessary to prepare for the installation of SUSE Linux Enterprise Server on ARM AArch64 computers. It introduces the steps required to prepare for various installation methods. The list of hardware requirements provides an overview of systems supported by SUSE Linux Enterprise Server. Find information about available installation methods and several common known problems. Also learn how to control the installation, provide installation media, and boot with regular methods.

5.1 System Requirements for Operating Linux

  • Filename: deployment_prep_aarch64_nsysreqs.xml
  • ID: sec.aarch64.sysreqs

The SUSE® Linux Enterprise Server operating system can be deployed on a wide range of hardware. It is impossible to list all the different combinations of hardware SUSE Linux Enterprise Server supports. However, to provide you with a guide to help you during the planning phase, the minimum requirements are presented here.

If you want to be sure that a given computer configuration will work, find out which platforms have been certified by SUSE. Find a list at https://www.suse.com/yessearch/.

5.1.1 Hardware for ARM AArch64

CPU

The minimum requirement is a CPU that supports the ARMv8-A instruction set architecture (ISA), for example, ARM Cortex-A53 or Cortex-A57. Refer to https://www.arm.com/products/processors/cortex-a/ for a list of available ARMv8-A processors.

CPUs with the ARMv8-R (realtime) and ARMv8-M (microcontroller) ISA are currently not supported.

Maximum Number of CPUs

The maximum number of CPUs supported by software design is 128. If you plan to use such a large system, check our hardware system certification Web page for supported devices, see https://www.suse.com/yessearch/.

Memory Requirements

A minimum of 1 GB of memory is required for a minimal installation. However, the minimum recommended is 1024 MB or 512 MB per CPU on multiprocessor computers. Add 150 MB for a remote installation via HTTP or FTP. Note that these values are only valid for the installation of the operating system—the actual memory requirement in production depends on the system's workload.

Hard Disk Requirements

The disk requirements depend largely on the installation selected and how you use your machine. Minimum requirements for different selections are:

System

Hard Disk Requirements

Minimal System

800 MB - 1GB

Minimal X Window System

1.4 GB

GNOME Desktop

3.5 GB

All patterns

8.5 GB

Using snapshots for virtualization

min. 8 GB

Boot Methods

The computer can be booted from a CD or a network. A special boot server is required to boot over the network. This can be set up with SUSE Linux Enterprise Server.

5.2 Installation Considerations

  • Filename: deployment_prep_aarch64_choose.xml
  • ID: sec.aarch64.prep.choose

This section encompasses many factors that need to be considered before installing SUSE Linux Enterprise Server on ARM AArch64 hardware.

5.2.1 Installation Type

SUSE Linux Enterprise Server is normally installed as an independent operating system. With the introduction of Virtualization, it is also possible to run multiple instances of SUSE Linux Enterprise Server on the same hardware. However, the installation of the VM Host Server is performed like a typical installation with some additional packages. The installation of virtual guests is described in Chapter 9, Guest Installation.

5.2.2 Boot Methods

Depending on the hardware used, the following boot methods are available for the first boot procedure (prior to the installation of SUSE Linux Enterprise Server).

Table 5.1: Boot Options

Boot Option

Use

CD or DVD drive

The simplest booting method. The system requires a locally-available CD-ROM or DVD-ROM drive for this.

Flash disks

Find the images required for creating boot disks on the first CD or DVD in the /boot directory. See also the README in the same directory. Booting from a USB memory stick is only possible if the BIOS of the machine supports this method.

PXE or bootp

Must be supported by the firmware of the system used. This option requires a boot server in the network. This task can be handled by a separate SUSE Linux Enterprise Server.

Hard disk

SUSE Linux Enterprise Server can also be booted from hard disk. For this, copy the kernel (linux) and the installation system (initrd) from the /boot/loader directory of the first CD or DVD onto the hard disk and add an appropriate entry to the boot loader.

5.2.3 Installation Source

When installing SUSE Linux Enterprise Server, the actual installation data must be available on the network, a hard disk partition, or a local DVD. To install from the network, you need an installation server. To make the installation data available, set up any computer in a Unix or Linux environment as an NFS, HTTP, SMB, or FTP server. To make the installation data available from a Windows computer, release the data with SMB.

The installation source is particularly easy to select if you configure an SLP server in the local network. For more information, see Chapter 8, Setting Up the Server Holding the Installation Sources.

5.2.4 Installation Target

Most installations are to a local hard disk. Therefore, it is necessary for the hard disk controllers to be available to the installation system. If a special controller (like a RAID controller) needs an extra kernel module, provide a kernel module update disk to the installation system.

Other installation targets may be various types of block devices that provide sufficient disk space and speed to run an operating system. This includes network block devices like iSCSI or SAN. It is also possible to install on network file systems that offer the standard Unix permissions. However, it may be problematic to boot these, because they must be supported by the initramfs before the actual system can start. Such installations are useful if there is a need to start the same system in different locations.

5.2.5 Different Installation Methods

SUSE Linux Enterprise Server offers several methods for controlling installation:

  • Installation on the graphical console

  • Installation via serial console

  • Installation with AutoYaST

  • Installation with KIWI images

  • Installation via SSH

  • Installation with VNC

By default, the graphical console is used. If you have many similar computers to install, it is advisable to create an AutoYaST configuration file or a KIWI preload image and make this available to the installation process. See also the documentation for AutoYaST at https://www.suse.com/documentation/sles-12/book_autoyast/data/book_autoyast.html and KIWI at http://doc.opensuse.org/projects/kiwi/doc/.

5.3 Boot and Installation Media

  • Filename: deployment_prep_aarch64_makeavail.xml
  • ID: sec.aarch64.instserver

When installing the system, the media for booting and for installing the system may be different. All combinations of supported media for booting and installing may be used.

5.3.1 Boot Media

Booting a computer depends on the capabilities of the hardware used and the availability of media for the respective boot option.

Booting from DVD

This is the most common possibility of booting a system. It is straightforward for most computer users, but requires a lot of interaction for every installation process.

Booting from a USB Flash Drive

Depending on the hardware used, it is possible to boot from a USB hard disk. The respective media must be created as described in Section 6.2.2, “PC (AMD64/Intel 64/ARM AArch64): System Start-up”.

Booting from the Network

You can only boot a computer directly from the network if this is supported by the computer's firmware. This booting method requires a boot server that provides the needed boot images over the network. The exact protocol depends on your hardware. Commonly you need several services, such as TFTP and DHCP or PXE boot. If you need a boot server, also read Section 10.1.3, “Remote Installation via VNC—PXE Boot and Wake on LAN”.

5.3.2 Installation Media

The installation media contain all the necessary packages and meta information that is necessary to install a SUSE Linux Enterprise Server. These must be available to the installation system after booting for installation. Several possibilities for providing the installation media to the system are available with SUSE Linux Enterprise Server.

Installation from DVD

All necessary data is delivered on the boot media. Depending on the selected installation, a network connection or add-on media may be necessary.

Networked Installation

If you plan to install several systems, providing the installation media over the network makes things a lot easier. It is possible to install from many common protocols, such as NFS, HTTP, FTP, or SMB. For more information on how to run such an installation, refer to Chapter 10, Remote Installation.

5.4 Installation Procedure

  • Filename: deployment_prep_aarch64_workflow.xml
  • ID: sec.aarch64.prep.worklfow

This section offers an overview of the steps required for the complete installation of SUSE® Linux Enterprise Server in the required mode. Part II, “The Installation Workflow” contains a full description of how to install and configure the system with YaST.

5.4.1 Booting from a Local Interchangeable Drive

DVD-ROM and USB storage devices can be used for installation purposes. Adjust your computer to your needs:

  1. Make sure that the drive is entered as a bootable drive in the firmware.

  2. Insert the boot medium in the drive and start the boot procedure.

  3. The installation boot menu of SUSE Linux Enterprise Server allows transferring different parameters to the installation system. See also Section 10.2.2, “Using Custom Boot Options”. If the installation should be performed over the network, specify the installation source here.

  4. If unexpected problems arise during installation, use safe settings to boot.

5.4.2 Installing over the Network

An installation server is required to perform the installation by using a network source. The procedure for installing this server is outlined in Chapter 8, Setting Up the Server Holding the Installation Sources.

If you have an SLP server, select SLP as the installation source in the first boot screen. During the boot procedure, select which of the available installation sources to use.

If the DVD is available on the network, use it as an installation source. In this case, specify the parameter install=<URL> with suitable values at the boot prompt. Find a more detailed description of this parameter in Section 10.2.2, “Using Custom Boot Options”.

5.5 Controlling the Installation

  • Filename: deployment_prep_aarch64_boot.xml
  • ID: sec.prep.boot.aarch64

Control the installation in one of several ways. The method most frequently used is to install SUSE® Linux Enterprise Server from the computer console. Other options are available for different situations.

5.5.1 Installation on the Computer Console

The simplest way to install SUSE Linux Enterprise Server is using the computer console. With this method, a graphical installation program guides you through the installation. This installation method is discussed in detail in Chapter 6, Installation with YaST.

You can still perform the installation on the console without a working graphics mode. The text-based installation program offers the same functionality as the graphical version. Find some hints about navigation in this mode in Section 5.1, “Navigation in Modules”.

5.5.2 Installation Using a Serial Console

For this installation method, you need a second computer connected by a null modem cable to the computer on which to install SUSE Linux Enterprise Server. Hardware and firmware of both machines need to support the serial console. Some firmware implementations are already configured to send the boot console output to a serial console (by providing a device tree with /chosen/stdout-path set appropriately). In this case no additional configuration is required.

If the firmware is not set up to use the serial console for the boot console output, you need to provide the following boot parameter at the boot prompt of the installation system (see Section 12.2.5, “Editing Menu Entries during the Boot Procedure” for details): console=TTY,BAUDRATE

BAUDRATE needs to be replaced by the baud rate for the interface. Valid values are 115200, 38400, or 9600. TTY needs to be replaced by the name of the interface. On most computers, there is one or more serial interfaces. Depending on the hardware, the names of the interfaces may vary:

  • ttyS0 for APM

  • ttyAMA0 for Server Base System Architecture (SBSA)

  • ttyPS0 for Xilinx

For the installation, you need a terminal program like minicom or screen. To initiate the serial connection, launch the screen program in a local console by entering the following command:

screen /dev/ttyUSB0 115200

This means that screen listens to the first serial port with a baud rate of 115200. From this point on, the installation proceeds similarly to the text-based installation over this terminal.

5.5.3 Installation with SSH

If you do not have direct access to the machine and the installation must be initiated from a management console, you can control the entire installation process over the network. To do this, enter the parameters ssh=1 and ssh.password=SECRET at the boot prompt. An SSH daemon is then launched in the system and you can log in as user root with the password SECRET.

To connect, use ssh -X. X-Forwarding over SSH is supported, if you have a local X server available. Otherwise, YaST provides a text interface over ncurses. YaST then guides you through the installation. This procedure is described in detail in Section 10.1.5, “Simple Remote Installation via SSH—Dynamic Network Configuration”.

If you do not have a DHCP server available in your local network, manually assign an IP address to the installation system. Do this by entering the option HostIP=IPADDR at the boot prompt.

5.5.4 Installation over VNC

If you do not have direct access to the system, but want a graphical installation, install SUSE Linux Enterprise Server over VNC. This method is described in detail in Section 10.3.1, “VNC Installation”.

As suitable VNC clients are also available for other operating systems, such as Microsoft Windows and mac OS, the installation can also be controlled from computers running those operating systems.

5.5.5 Installation with AutoYaST

If you need to install SUSE Linux Enterprise Server on several computers with similar hardware, it is recommended you perform the installations with the aid of AutoYaST. In this case, start by installing one SUSE Linux Enterprise Server and use this to create the necessary AutoYaST configuration files.

5.6 Dealing with Boot and Installation Problems

  • Filename: aarch64_inst_problem.xml
  • ID: sec.bootproblem.aarch64

Prior to delivery, SUSE® Linux Enterprise Server is subjected to an extensive test program. Despite this, problems occasionally occur during boot or installation.

5.6.1 Problems Booting

Boot problems may prevent the YaST installer from starting on your system. Another symptom is when your system does not boot after the installation has been completed.

Installed System Boots, Not Media

Change your computer's firmware so that the boot sequence is correct. To do this, consult the manual for your hardware.

The Computer Hangs

Change the console on your computer so that the kernel outputs are visible. Be sure to check the last outputs. This is normally done by pressing CtrlAltF10. If you cannot resolve the problem, consult the SUSE Linux Enterprise Server support staff. To log all system messages at boot time, use a serial connection as described in Section 2.5, “Controlling the Installation”.

Boot Disk

The boot disk is a useful interim solution if you have difficulties setting the other configurations or if you want to postpone the decision regarding the final boot mechanism. For more details on creating boot disks, see grub2-mkrescue.

5.6.2 Problems Installing

If an unexpected problem occurs during installation, information is needed to determine the cause of the problem. Use the following directions to help with troubleshooting:

  • Check the outputs on the various consoles. You can switch consoles with the key combination CtrlAltFn. For example, obtain a shell in which to execute various commands by pressing CtrlAltF2.

  • Try launching the installation with Safe Settings (press F5 on the installation screen and choose Safe Settings). If the installation works without problems in this case, there is an incompatibility that causes either ACPI or APIC to fail. In some cases, a firmware update fixes this problem.

  • Check the system messages on a console in the installation system by entering the command dmesg -T.

5.6.3 Redirecting the Boot Source to the Boot DVD

To simplify the installation process and avoid accidental installations, the default setting on the installation DVD for SUSE Linux Enterprise Server is that your system is booted from the first hard disk. At this point, an installed boot loader normally takes over control of the system. This means that the boot DVD can stay in the drive during an installation. To start the installation, choose one of the installation possibilities in the boot menu of the media.

Part II The Installation Workflow

6 Installation with YaST

After your hardware has been prepared for the installation of SUSE® Linux Enterprise Server as described in Part I, “Installation Preparation” and after the connection with the installation system has been established, you are presented with the interface of SUSE Linux Enterprise Server's system assistant YaST. YaST guides you through the entire installation.

During the installation process, YaST analyzes both your current system settings and your hardware components. Based on this analysis your system will be set up with a basic configuration including networking (provided the system could be configured using DHCP). To fine-tune the system after the installation has finished, start YaST from the installed system.

7 Cloning Disk Images

If SUSE Linux Enterprise Server is installed in a virtualized environment, cloning an existing installation may be the fastest way to deploy further machines. SUSE Linux Enterprise Server provides a script to clean up configuration that is unique to each installation. With the introduction of system…

6 Installation with YaST

  • Filename: inst_yast2.xml
  • ID: cha.inst
Abstract

After your hardware has been prepared for the installation of SUSE® Linux Enterprise Server as described in Part I, “Installation Preparation” and after the connection with the installation system has been established, you are presented with the interface of SUSE Linux Enterprise Server's system assistant YaST. YaST guides you through the entire installation.

During the installation process, YaST analyzes both your current system settings and your hardware components. Based on this analysis your system will be set up with a basic configuration including networking (provided the system could be configured using DHCP). To fine-tune the system after the installation has finished, start YaST from the installed system.

6.1 Choosing the Installation Method

After having selected the installation medium, determine the suitable installation method and boot option that best matches your needs:

Installing from the SUSE Linux Enterprise Server Media (DVD, USB)

Choose this option if you want to perform a stand-alone installation and do not want to rely on a network to provide the installation data or the boot infrastructure. The installation proceeds exactly as outlined in Section 6.3, “Steps of the Installation”.

Installing from a Network Server

Choose this option if you have an installation server available in your network or want to use an external server as the source of your installation data. This setup can be configured to boot from physical media (flash disk, CD/DVD, or hard disk) or configured to boot via network using PXE/BOOTP. Refer to Section 6.2, “System Start-up for Installation” for details.

The installation program configures the network connection with DHCP and retrieves the location of the network installation source from the OpenSLP server. If no DHCP is available, choose F4 Source › Network Config › Manual and enter the network data. On EFI systems modify the network boot parameters as described in Section 6.2.2.2, “The Boot Screen on Machines Equipped with UEFI”.

Installing from an SLP Server.  If your network setup supports OpenSLP and your network installation source has been configured to announce itself via SLP (described in Chapter 8, Setting Up the Server Holding the Installation Sources), boot the system, press F4 in the boot screen and select SLP from the menu. On EFI systems set the install parameter to install=slp:/ as described in Section 6.2.2.2, “The Boot Screen on Machines Equipped with UEFI”.

Installing from a Network Source without SLP.  If your network setup does not support OpenSLP for the retrieval of network installation sources, boot the system and press F4 in the boot screen to select the desired network protocol (NFS, HTTP, FTP, or SMB/CIFS) and provide the server's address and the path to the installation media. On EFI systems modify the boot parameter install= as described in Section 6.2.2.2, “The Boot Screen on Machines Equipped with UEFI”.

6.2 System Start-up for Installation

The way the system is started for the installation depends on the architecture—system start-up is different for PC (AMD64/Intel 64) or mainframe, for example. If you install SUSE Linux Enterprise Server as a VM Guest on a KVM or Xen hypervisor, follow the instructions for the AMD64/Intel 64 architecture.

6.2.1 IBM z Systems: System Start-up

For IBM z Systems platforms, the system is booted (IPL, Initial Program Load) as described in Section 4.2.4, “IPLing the SUSE Linux Enterprise Server Installation System”. SUSE Linux Enterprise Server does not show a splash screen on these systems. During the installation, load the kernel, initrd, and parmfile manually. YaST starts with its installation screen when a connection has been established to the installation system via VNC, X, or SSH. Because there is no splash screen, kernel or boot parameters cannot be entered on screen, but must be specified in a parmfile (see Section 4.3, “The parmfile—Automating the System Configuration”).

6.2.2 PC (AMD64/Intel 64/ARM AArch64): System Start-up

SUSE Linux Enterprise Server supports several boot options from which you can choose, depending on the hardware available and on the installation scenario you prefer. Booting from the SUSE Linux Enterprise Server media is the most straightforward option, but special requirements might call for special setups:

Table 6.1: Boot Options

Boot Option

Description

DVD

This is the easiest boot option. This option can be used if the system has a local DVD-ROM drive that is supported by Linux.

Flash Disks (USB Mass Storage Device)

In case your machine is not equipped with an optical drive, you can boot the installation image from a flash disk. To create a bootable flash disk, you need to copy either the DVD or the Mini CD ISO image to the device using the dd command (the flash disk must not be mounted, all data on the device will be erased):

dd if=PATH_TO_ISO_IMAGE of=USB_STORAGE_DEVICE bs=4M
Important
Important: Compatibility

Note that booting from a USB Mass Storage Device is not supported on UEFI machines and on the POWER architecture.

PXE or BOOTP

Booting over the network must be supported by the system's BIOS or firmware, and a boot server must be available in the network. This task can also be handled by another SUSE Linux Enterprise Server system. Refer to Chapter 10, Remote Installation for more information.

Hard Disk

SUSE Linux Enterprise Server installation can also be booted from the hard disk. To do this, copy the kernel (linux) and the installation system (initrd) from the directory /boot/ARCHITECTURE/ on the installation media to the hard disk and add an appropriate entry to the existing boot loader of a previous SUSE Linux Enterprise Server installation.

Tip
Tip: Booting from DVD on UEFI Machines

DVD1 can be used as a boot medium for machines equipped with UEFI (Unified Extensible Firmware Interface). Refer to your vendor's documentation for specific information. If booting fails, try to enable CSM (Compatibility Support Module) in your firmware.

Note
Note: Add-on Product Installation Media

Media for add-on products (extensions or third-party products) cannot be used as stand-alone installation media. They can either be embedded as additional installation sources during the installation process (see Section 6.9, “Extension Selection”) or be installed from the running system using the YaST Add-on Products module (see Chapter 14, Installing Modules, Extensions, and Third Party Add-On Products for details).

6.2.2.1 The Boot Screen on Machines Equipped with Traditional BIOS

The boot screen displays several options for the installation procedure. Boot from Hard Disk boots the installed system and is selected by default, because the CD is often left in the drive. Select one of the other options with the arrow keys and press Enter to boot it. The relevant options are:

Installation

The normal installation mode. All modern hardware functions are enabled. In case the installation fails, see F5Kernel for boot options that disable potentially problematic functions.

Upgrade

Perform a system upgrade. For more information refer to Chapter 19, Upgrading SUSE Linux Enterprise.

Rescue System

Starts a minimal Linux system without a graphical user interface. For more information, see Section 40.6.2, “Using the Rescue System”.

Check Installation Media

This option is only available when you install from media created from downloaded ISOs. In this case it is recommended to check the integrity of the installation medium. This option starts the installation system before automatically checking the media. In case the check was successful, the normal installation routine starts. If a corrupt media is detected, the installation routine aborts.

Warning
Warning: Failure of Media Check

If the media check fails, your medium is damaged. Do not continue the installation because installation may fail or you may lose your data. Replace the broken medium and restart the installation process.

Memory Test

Tests your system RAM using repeated read and write cycles. Terminate the test by rebooting. For more information, see Section 40.2.4, “Fails to Boot”.

The Boot Screen on Machines with a Traditional BIOS
Figure 6.1: The Boot Screen on Machines with a Traditional BIOS

Use the function keys shown at the bottom of the screen to change the language, screen resolution, installation source or to add an additional driver from your hardware vendor:

F1Help

Get context-sensitive help for the active element of the boot screen. Use the arrow keys to navigate, Enter to follow a link, and Esc to leave the help screen.

F2Language

Select the display language and a corresponding keyboard layout for the installation. The default language is English (US).

F3Video Mode

Select various graphical display modes for the installation. By Default the video resolution is automatically determined using KMS (Kernel Mode Setting). If this setting does not work on your system, choose No KMS and, optionally, specify vga=ask on the boot command line to get prompted for the video resolution. Choose Text Mode if the graphical installation causes problems.

F4Source

Normally, the installation is performed from the inserted installation medium. Here, select other sources, like FTP or NFS servers. If the installation is deployed on a network with an SLP server, select an installation source available on the server with this option. Find information about setting up an installation server with SLP at Chapter 8, Setting Up the Server Holding the Installation Sources.

F5Kernel

If you encounter problems with the regular installation, this menu offers to disable a few potentially problematic functions. If your hardware does not support ACPI (advanced configuration and power interface) select No ACPI to install without ACPI support. No local APIC disables support for APIC (Advanced Programmable Interrupt Controllers) which may cause problems with some hardware. Safe Settings boots the system with the DMA mode (for CD/DVD-ROM drives) and power management functions disabled.

If you are not sure, try the following options first: Installation—ACPI Disabled or Installation—Safe Settings. Experts can also use the command line (Boot Options) to enter or change kernel parameters.

F6Driver

Press this key to notify the system that you have an optional driver update for SUSE Linux Enterprise Server. With File or URL, load drivers directly before the installation starts. If you select Yes, you are prompted to insert the update disk at the appropriate point in the installation process.

Tip
Tip: Getting Driver Update Disks

Driver updates for SUSE Linux Enterprise are provided at http://drivers.suse.com/. These drivers have been created via the SUSE SolidDriver Program.

6.2.2.2 The Boot Screen on Machines Equipped with UEFI

UEFI (Unified Extensible Firmware Interface) is a new industry standard which replaces and extends the traditional BIOS. The latest UEFI implementations contain the Secure Boot extension, which prevents booting malicious code by only allowing signed boot loaders to be executed. See Chapter 11, UEFI (Unified Extensible Firmware Interface) for more information.

The boot manager GRUB 2, used to boot machines with a traditional BIOS, does not support UEFI, therefore GRUB 2 is replaced with GRUB 2 for EFI. If Secure Boot is enabled, YaST will automatically select GRUB 2 for EFI for installation. From an administrative and user perspective, both boot manager implementations behave the same and are called GRUB 2 in the following.

Tip
Tip: UEFI and Secure Boot are Supported by Default

The installation routine of SUSE Linux Enterprise Server automatically detects if the machine is equipped with UEFI. All installation sources also support Secure Boot. If an EFI system partition already exists on dual boot machines (from a Microsoft Windows 8 installation, for example), it will automatically be detected and used. Partition tables will be written as GPT on UEFI systems.

Warning
Warning: Using Non-Inbox Drivers with Secure Boot

There is no support for adding non-inbox drivers (that is, drivers that do not come with SLE) during installation with Secure Boot enabled. The signing key used for SolidDriver/PLDP is not trusted by default.

To solve this problem, it is necessary to either add the needed keys to the firmware database via firmware/system management tools before the installation or to use a bootable ISO that will enroll the needed keys in the MOK list at first boot. For more information, see Section 11.1, “Secure Boot”.

The boot screen displays several options for the installation procedure. Change the selected option with the arrow keys and press Enter to boot it. The relevant options are:

Installation

The normal installation mode.

Upgrade

Perform a system upgrade. For more information refer to Chapter 19, Upgrading SUSE Linux Enterprise.

Rescue System

Starts a minimal Linux system without a graphical user interface. For more information, see Section 40.6.2, “Using the Rescue System”.

Check Installation Media

This option is only available when you install from media created from downloaded ISOs. In this case it is recommended to check the integrity of the installation medium. This option starts the installation system before automatically checking the media. In case the check was successful, the normal installation routine starts. If a corrupt media is detected, the installation routine aborts.

The Boot Screen on Machines with UEFI
Figure 6.2: The Boot Screen on Machines with UEFI

GRUB 2 for EFI on SUSE Linux Enterprise Server does not support a boot prompt or function keys for adding boot parameters. By default, the installation will be started with American English and the boot media as the installation source. A DHCP lookup will be performed to configure the network. To change these defaults or to add additional boot parameters you need to edit the respective boot entry. Highlight it using the arrow keys and press E. See the on-screen help for editing hints (note that only an English keyboard is available now). The Installation entry will look similar to the following:

setparams 'Installation'

    set gfxpayload=keep
    echo 'Loading kernel ...'
    linuxefi /boot/x86_64/loader/linux splash=silent
    echo 'Loading initial ramdisk ...'
    initrdefi /boot/x86_64/loader/initrd

Add space-separated parameters to the end of the line starting with linuxefi. To boot the edited entry, press F10. If you access the machine via serial console, press Esc0. A complete list of parameters is available at http://en.opensuse.org/Linuxrc. The most important ones are:

Table 6.2: Installation Sources

CD/DVD (default)

install=cd:/

Hard disk

install=hd:/?device=sda/PATH_TO_ISO

SLP

install=slp:/

FTP

install=ftp://ftp.example.com/PATH_TO_ISO

HTTP

install=http://www.example.com/PATH_TO_ISO

NFS

install=nfs:/PATH_TO_ISO

SMB / CIFS

install=smb://PATH_TO_ISO

Table 6.3: Network Configuration

DHCP (default)

netsetup=dhcp

Prompt for Parameters

netsetup=hostip,netmask,gateway,nameserver

Host IP address

hostip=192.168.2.100

hostip=192.168.2.100/24

Netmask

netmask=255.255.255.0

Gateway

gateway=192.168.5.1

Name Server

nameserver=192.168.1.116

nameserver=192.168.1.116,192.168.1.118

Domain Search Path

domain=example.com

Table 6.4: Miscellaneous

Driver Updates: Prompt

dud=1

Driver Updates: URL

dud=ftp://ftp.example.com/PATH_TO_DRIVER

dud=http://www.example.com/PATH_TO_DRIVER

Installation Language

Language=LANGUAGE

Supported values for LANGUAGE are, among others, cs_CZ, de_DE, es_ES, fr_FR, ja_JP, pt_BR, pt_PT, ru_RU, zh_CN, and zh_TW.

Kernel: No ACPI

acpi=off

Kernel: No Local APIC

noapic

Video: Disable KMS

nomodeset

Video: Start Installer in Text Mode

Textmode=1

6.2.3 Boot Parameters for Advanced Setups

To configure access to a local SMT or supportconfig server for the installation, you can specify boot parameters to set up these services during installation. The same applies if you need IPv6 support during the installation.

6.2.3.1 Providing Data to Access an SMT Server

By default, updates for SUSE Linux Enterprise Server are delivered by the SUSE Customer Center. If your network provides a so called SMT server to provide a local update source, you need to equip the client with the server's URL. Client and server communicate solely via HTTPS protocol, therefore you also need to enter a path to the server's certificate if the certificate was not issued by a certificate authority.

Note
Note: Non-Interactive Installation Only

Providing parameters for accessing an SMT server is only needed for non-interactive installations. During an interactive installation the data can be provided during the installation (see Section 6.8, “SUSE Customer Center Registration” for details).

regurl

URL of the SMT server. This URL has a fixed format https://FQN/center/regsvc/. FQN needs to be a fully qualified host name of the SMT server. Example:

regurl=https://smt.example.com/center/regsvc/
regcert

Location of the SMT server's certificate. Specify one of the following locations:

URL

Remote location (HTTP, HTTPS or FTP) from which the certificate can be downloaded. Example:

regcert=http://smt.example.com/smt-ca.crt
local path

Absolute path to the certificate on the local machine. Example:

regcert=/data/inst/smt/smt-ca.cert
Interactive

Use ask to open a pop-up menu during the installation where you can specify the path to the certificate. Do not use this option with AutoYaST. Example

regcert=ask
Deactivate certificate installation

Use done if the certificate will be installed by an add-on product, or if you are using a certificate issued by an official certificate authority. For example:

regcert=done
Warning
Warning: Beware of Typing Errors

Make sure the values you enter are correct. If regurl has not been specified correctly, the registration of the update source will fail. If a wrong value for regcert has been entered, you will be prompted for a local path to the certificate.

In case regcert is not specified, it will default to http://FQN/smt.crt with FQN being the name of the SMT server.

6.2.3.2 Configuring an Alternative Data Server for supportconfig

The data that supportconfig (see Chapter 39, Gathering System Information for Support for more information) gathers is sent to the SUSE Customer Center by default. It is also possible to set up a local server to collect this data. If such a server is available on your network, you need to set the server's URL on the client. This information needs to be entered at the boot prompt.

supporturl URL of the server. The URL has the format http://FQN/Path/, where FQN is the fully qualified host name of the server and Path is the location on the server. For example:

supporturl=http://support.example.com/supportconfig/data/

6.2.3.3 Using IPv6 During the Installation

By default you can only assign IPv4 network addresses to your machine. To enable IPv6 during installation, enter one of the following parameters at the boot prompt:

Accept IPv4 and IPv6
ipv6=1
Accept IPv6 only
ipv6only=1

6.2.3.4 Using a Proxy During the Installation

In networks enforcing the usage of a proxy server for accessing remote Web sites, registration during installation is only possible when configuring a proxy server.

To use a proxy during the installation, press F4 on the boot screen and set the required parameters in the HTTP Proxy dialog. Alternatively provide the kernel parameter proxy at the boot prompt:

l>proxy=http://USER:PASSWORD@proxy.example.com:PORT

Specifying USER and PASSWORD is optional—if the server allows anonymous access, the following data is sufficient: http://proxy.example.com:PORT.

6.2.3.5 Enabling SELinux Support

Enabling SELinux upon installation start-up enables you to configure it after the installation has been finished without having to reboot. Use the following parameters:

security=selinux selinux=1

6.2.3.6 Enabling the Installer Self-Update

During installation and upgrade, YaST can update itself as described in Section 6.4, “Installer Self-Update” to solve potential bugs discovered after release. The self_update parameter can be used to modify the behavior of this feature.

To enable the installer self-update, set the parameter to 1:

self_update=1

To use a user-defined repository, specify a URL:

self_update=https://updates.example.com/

6.3 Steps of the Installation

The interactive installation of SUSE Linux Enterprise Server split into several steps is listed below.

After starting the installation, SUSE Linux Enterprise Server loads and configures a minimal Linux system to run the installation procedure. To view the boot messages and copyright notices during this process, press Esc. On completion of this process, the YaST installation program starts and displays the graphical installer.

Tip
Tip: Installation Without a Mouse

If the installer does not detect your mouse correctly, use →| for navigation, arrow keys to scroll, and Enter to confirm a selection. Various buttons or selection fields contain a letter with an underscore. Use AltLetter to select a button or a selection directly instead of navigating there with →|.

6.4 Installer Self-Update

During the installation and upgrade process, YaST is able to update itself to solve bugs in the installer that were discovered after the release. This functionality is enabled by default; to disable it, set the boot parameter self_update to 0. For more information, see Section 6.2.3.6, “Enabling the Installer Self-Update”.

Although this feature was designed to run without user intervention, it is worth knowing how it works. If you are not interested, you can jump directly to Section 6.5, “Language, Keyboard and License Agreement” and skip the rest of this section.

Tip
Tip: Language Selection

The installer self-update is executed before the language selection step. This means that progress and errors which happen during this process are displayed in English by default.

To use another language for this part of the installer, press F2 in the DVD boot menu and select the language from the list. Alternatively, use the language boot parameter (for example, language=de_DE).

6.4.1 Self-Update Process

The process can be broken down into two different parts:

  1. Determine the update repository location.

  2. Download and apply the updates to the installation system.

6.4.1.1 Determining the Update Repository Location

Installer Self-Updates are distributed as regular RPM packages via a dedicated repository, so the first step is to find out the repository URL.

Important
Important: Installer Self-Update Repository Only

No matter which of the following options you use, only the installer self-update repository URL is expected, for example:

self_update=https://www.example.com/my_installer_updates/

Do not supply any other repository URL—for example the URL of the software update repository.

YaST will try the following sources of information:

  1. The self_update boot parameter. (For more details, see Section 6.2.3.6, “Enabling the Installer Self-Update”.) If you specify a URL, it will take precedence over any other method.

  2. The /general/self_update_url profile element in case you are using AutoYaST.

  3. A registration server. YaST will query the registration server for the URL. The server to be used is determined in the following order:

    1. By evaluating the regurl boot parameter (Section 6.2.3.1, “Providing Data to Access an SMT Server”).

    2. By evaluating the /suse_register/reg_server profile element if you are using AutoYaST.

    3. By performing an SLP lookup. If an SLP server is found, YaST will ask you whether it should be used because there is no authentication involved and everybody on the local network could announce a registration server.

    4. By querying the SUSE Customer Center.

  4. If none of the previous attempts worked, the fallback URL (defined in the installation media) will be used.

6.4.1.2 Downloading and Applying the Updates

When the updates repository is determined, YaST will check whether an update is available. If so, all the updates will be downloaded and applied to the installation system.

Finally, YaST will be restarted to load the new version and the welcome screen will be shown. If no updates were available, the installation will continue without restarting YaST.

Note
Note: Update Integrity

Update signatures will be checked to ensure integrity and authorship. If a signature is missing or invalid, you will be asked whether you want to apply the update.

6.4.2 Networking during Self-Update

To download installer updates, YaST needs network access. By default, it tries to use DHCP on all network interfaces. If there is a DHCP server in the network, it will work automatically.

If you need a static IP setup, you can use the ifcfg boot argument. For more details, see the linuxrc documentation at https://en.opensuse.org/Linuxrc.

6.4.3 Custom Self-Update Repositories

YaST can use a user-defined repository instead of the official one by specifying a URL through the self_update boot option. However, the following points should be considered:

  • Only HTTP/HTTPS and FTP repositories are supported.

  • Only RPM-MD repositories are supported (required by SMT).

  • Packages are not installed in the usual way: They are uncompressed only and no scripts are executed.

  • No dependency checks are performed. Packages are installed in alphabetical order.

  • Files from the packages override the files from the original installation media. This means that the update packages might not need to contain all files, only files that have changed. Unchanged files are omitted to save memory and download bandwidth.

Note
Note: Only One Repository

Currently, it is not possible to use more than one repository as source for installer self-updates.

6.5 Language, Keyboard and License Agreement

Start the installation of SUSE Linux Enterprise Server by choosing your language. Changing the language will automatically preselect a corresponding keyboard layout. Override this proposal by selecting a different keyboard layout from the drop-down box. The language selected here is also used to assume a time zone for the system clock. This setting can be modified later in the installed system as described in Chapter 17, Changing Language and Country Settings with YaST.

Read the license agreement that is displayed beneath the language and keyboard selection thoroughly. Use License Translations to access translations. If you agree to the terms, check I Agree to the License Terms and click Next to proceed with the installation. If you do not agree to the license agreement, you cannot install SUSE Linux Enterprise Server; click Abort to terminate the installation.

Language, Keyboard and License Agreement
Figure 6.3: Language, Keyboard and License Agreement

6.6 IBM z Systems: Disk Activation

When installing on IBM z Systems platforms, the language selection dialog is followed by a dialog to configure the attached hard disks. Select DASD, Fibre Channel Attached SCSI Disks (zFCP), or iSCSI for installation of SUSE Linux Enterprise Server. The DASD and zFCP configuration buttons are only available if the corresponding devices are attached. For instructions on how to configure iSCSI disks, refer to Section 14.3, “Configuring iSCSI Initiator”.

You can also Change the Network Configuration in this screen by launching the Network Settings dialog. Choose a network interface from the list and click Edit to change its settings. Use the tabs to configure DNS and routing. See Section 16.4, “Configuring a Network Connection with YaST” for more details.

Disk Activation
Figure 6.4: Disk Activation

6.6.1 Configuring DASD Disks

After selecting Configure DASD Disks, an overview lists all available DASDs. To get a clearer picture of the available devices, use the text box located above the list to specify a range of channels to display. To filter the list according to such a range, select Filter.

IBM z Systems: Selecting a DASD
Figure 6.5: IBM z Systems: Selecting a DASD

Specify the DASDs to use for the installation by selecting the corresponding entries in the list. Use Select All to select all DASDs currently displayed. Activate and make the selected DASDs available for the installation by selecting Perform Action › Activate. To format the DASDs, select Perform Action › Format. Alternatively, use the YaST partitioner later as described in Section 12.1, “Using the YaST Partitioner”.

6.6.2 Configuring zFCP Disks

To use zFCP disks for the SUSE Linux Enterprise Server installation, select Configure zFCP Disks in the selection dialog. This opens a dialog with a list of the zFCP disks available on the system. In this dialog, select Add to open another dialog in which to enter zFCP parameters.

To make a zFCP disk available for the SUSE Linux Enterprise Server installation, choose an available Channel Number from the drop-down box. Get WWPNs (World Wide Port Number) and Get LUNs (Logical Unit Number) return lists with available WWPNs and FCP-LUNs, respectively, to choose from. Automatic LUN scanning only works with NPIV enabled.

When completed, exit the zFCP dialog with Next and the general hard disk configuration dialog with Finish to continue with the rest of the configuration.

6.7 Network Settings

After booting into the installation, the installation routine is set up. During this setup, an attempt to configure at least one network interface with DHCP is made. In case this attempt fails, the Network Settings dialog launches. Choose a network interface from the list and click Edit to change its settings. Use the tabs to configure DNS and routing. See Section 16.4, “Configuring a Network Connection with YaST” for more details. On IBM z Systems this dialog does not start automatically. It can be started in the Disk Activation step.

In case DHCP was successfully configured during installation setup, you can also access this dialog by clicking Network Configuration at the SUSE Customer Center Registration step. It lets you change the automatically provided settings.

Note
Note: Network Interface Configured via linuxrc

If at least one network interface is configured via linuxrc, automatic DHCP configuration is disabled and configuration from linuxrc is imported and used.

Network Settings
Figure 6.6: Network Settings
Tip
Tip: Accessing Network Storage or Local RAID

To access a SAN or a local RAID during the installation, you can use the libstorage command line client for this purpose:

  1. Switch to a console with CtrlAltF2.

  2. Install the libstoragemgmt extension by running extend libstoragemgmt.

  3. Now you have access to the lsmcli command. For more information, run lsmcli --help.

  4. To return to the installer, press AltF7

Supported are Netapp Ontap, all SMI-S compatible SAN providers, and LSI MegaRAID.

6.8 SUSE Customer Center Registration

To get technical support and product updates, you need to register and activate your product with the SUSE Customer Center. Registering SUSE Linux Enterprise Server now grants you immediate access to the update repository. This enables you to install the system with the latest updates and patches available. If you are offline or want to skip this step, select Skip Registration. You can register your system at any time later from the installed system.

Note
Note: Network Configuration

After booting into the installation, the installation routine is set up. During this setup, an attempt to configure all network interfaces with DHCP is made. If DHCP is not available or you want to modify the network configuration, click Network Configuration in the upper right corner of the SUSE Customer Center Registration screen. The YaST module Network Settings opens. See Section 16.4, “Configuring a Network Connection with YaST” for details.

SUSE Customer Center Registration
Figure 6.7: SUSE Customer Center Registration

To register your system, provide the E-mail address associated with the SUSE account you or your organization uses to manage subscriptions. In case you do not have a SUSE account yet, go to the SUSE Customer Center home page (https://scc.suse.com/) to create one.

Enter the Registration Code you received with your copy of SUSE Linux Enterprise Server. YaST can also read registration codes from a USB storage device such as a flash disk. For details, see Section 6.8.1, “Loading Registration Codes from USB Storage”.

Proceed with Next to start the registration process. If one or more local registration servers are available on your network, you can choose one of them from a list. By default, SUSE Linux Enterprise Server is registered at the SUSE Customer Center. If your local registration server was not discovered automatically, choose Cancel, select Register System via local SMT Server and enter the URL of the server. Restart the registration by choosing Next again.

During the registration, the online update repositories will be added to your installation setup. When finished, you can choose whether to install the latest available package versions from the update repositories. This ensures that SUSE Linux Enterprise Server is installed with the latest security updates available. If you choose No, all packages will be installed from the installation media. Proceed with Next.

If the system was successfully registered during installation, YaST will disable repositories from local installation media such as CD/DVD or flash disks when the installation has been completed. This prevents problems if the installation source is no longer available and ensures that you always get the latest updates from the online repositories.

Tip
Tip: Release Notes

From this point on, the Release Notes can be viewed from any screen during the installation process by selecting Release Notes.

6.8.1 Loading Registration Codes from USB Storage

To make the registration more convenient, you can also store your registration codes on a USB storage device such as a flash disk. YaST will automatically pre-fill the corresponding text box. This is particularly useful when testing the installation or if you need to register many systems or extensions.

Note
Note: Limitations

Currently flash disks are only scanned during installation or upgrade, but not when registering a running system.

Create a file named regcodes.txt or regcodes.xml on the USB disk. If both are present, the XML takes precedence.

In that file, identify the product with the name returned by zypper search --type product and assign it a registration code as follows:

Example 6.1: regcodes.txt
SLES    cc36aae1
SLED    309105d4

sle-we  5eedd26a
sle-live-patching 8c541494
Example 6.2: regcodes.xml
<?xml version="1.0"?>
<profile xmlns="http://www.suse.com/1.0/yast2ns"
 xmlns:config="http://www.suse.com/1.0/configns">
  <suse_register>
    <addons config:type="list">
      <addon>
<name>SLES</name>
<reg_code>cc36aae1</reg_code>
      </addon>
      <addon>
<name>SLED</name>
<reg_code>309105d4</reg_code>
      </addon>
      <addon>
<name>sle-we</name>
<reg_code>5eedd26a</reg_code>
      </addon>
      <addon>
<name>sle-live-patching</name>
<reg_code>8c541494</reg_code>
      </addon>
    </addons>
  </suse_register>
</profile>

Note that SLES and SLED are not extensions, but listing them as add-ons allows for combining several base product registration codes in a single file. See Section 4.3.1, “Extensions” for details.

6.9 Extension Selection

If you have successfully registered your system in the previous step, a list of available modules and extensions based on SUSE Linux Enterprise Server is shown. Otherwise this configuration step is skipped. It is also possible to add modules and extensions from the installed system, see Chapter 14, Installing Modules, Extensions, and Third Party Add-On Products for details.

The list contains free modules for SUSE Linux Enterprise Server, such as the SUSE Linux Enterprise SDK and extensions requiring a registration key that is liable for costs. Click an entry to see its description. Select a module or extension for installation by activating its check mark. This will add its repository from the SUSE Customer Center server to your installation—no additional installation sources are required. Furthermore the installation pattern for the module or extension is added to the default installation to ensure it gets installed automatically.

The amount of available extensions and modules depends on the registration server. A local registration server may only offer update repositories and no additional extensions.

Tip
Tip: Modules

Modules are fully supported parts of SUSE Linux Enterprise Server with a different life cycle. They have a clearly defined scope and are delivered via online channel only. Registering at the SUSE Customer Center is a prerequisite for being able to subscribe to these channels.

Tip
Tip: SUSE Linux Enterprise Desktop

As of SUSE Linux Enterprise 12, SUSE Linux Enterprise Desktop is not only available as a separate product, but also as a workstation extension for SUSE Linux Enterprise Server. If you register at the SUSE Customer Center, the SUSE Linux Enterprise Workstation Extension can be selected for installation. Note that installing it requires a valid registration key.

Extension Selection
Figure 6.8: Extension Selection

Proceed with Next to the Add-on Product dialog, where you can specify sources for additional add-on products not available on the registration server.

If you do not want to install add-ons, proceed with Next. Otherwise activate I would like to install an additional Add-on Product. Specify the Media Type by choosing from CD, DVD, Hard Disk, USB Mass Storage, a Local Directory or a Local ISO Image. If network access has been configured you can choose from additional remote sources such as HTTP, SLP, FTP, etc. Alternatively you may directly specify a URL. Check Download Repository Description Files to download the files describing the repository now. If deactivated, they will be downloaded after the installation starts. Proceed with Next and insert a CD or DVD if required.

Depending on the add-on's content, it may be necessary to accept additional license agreements. If you have chosen an add-on product requiring a registration key, you will be asked to enter it at the Extension and Module Registration Codes page. Proceed with Next.

Add-on Product
Figure 6.9: Add-on Product
Tip
Tip: No Registration Key Error

If you have chosen a product in the Extension Selection dialog for which you do not have a valid registration key, choose Back until you see the Extension Selection dialog. Deselect the module or extension and proceed with Next. Modules or extensions can also be installed at any time later from the running system as described in Chapter 14, Installing Modules, Extensions, and Third Party Add-On Products.

6.10 System Role

SUSE Linux Enterprise Server supports a broad range of features. To simplify the installation, YaST offers predefined use cases which adjust the system to be installed so it is tailored for the selected scenario. Currently this affects the package set and the suggested partitioning scheme.

Choose the System Role that meets your requirements best:

Default System

Select this scenario when installing on a “real” machine or a fully virtualized guest.

KVM Virtualization Host

Select this scenario when installing on a machine that should serve as a KVM host that can run other virtual machines.

Xen Virtualization Host

Select this scenario when installing on a machine that should serve as a Xen host that can run other virtual machines.

System Role Selection
Figure 6.10: System Role Selection

6.11 Suggested Partitioning

Define a partition setup for SUSE Linux Enterprise Server in this step. Depending on the system role, the installer creates a proposal for one of the disks available. All proposals contain a root partition formatted with Btrfs (with snapshots enabled) and a swap partition. If you have chosen the system role Default System in the previous step, a home partition formatted with XFS will be created, too. On hard disks smaller than 20 GB the proposal does not include a separate home partition. If one or more swap partitions have been detected on the available hard disks, these existing ones will be used (rather than proposing a new swap partition). You have several options to proceed:

Next

To accept the proposal without any changes, click Next to proceed with the installation workflow.

Edit Proposal Settings

To adjust the proposal choose Edit Proposal Settings. The pop-up dialog lets you switch to an LVM-based Proposal or an Encrypted LVM-based Proposal. You may also adjust file systems for the proposed partitions, create a separate home partition, and enlarge the swap partition (to enable suspend to disk, for example).

If the root file system format is Btrfs, you can also disable Btrfs snapshots here.

Create Partition Setup

Use this option to move the proposal described above to a different disk. Select a specific disk from the list. If the chosen hard disk does not contain any partitions yet, the whole hard disk will be used for the proposal. Otherwise, you can choose which existing partition(s) to use. Edit Proposal Settings lets you fine-tune the proposal.

Expert Partitioner

To create a custom partition setup choose Expert Partitioner. The Expert Partitioner opens, displaying the current partition setup for all hard disks, including the proposal suggested by the installer. You can Add, Edit, Resize, or Delete partitions.

You can also set up Logical Volumes (LVM), configure software RAID and device mapping (DM), encrypt Partitions, mount NFS shares and manage tmpfs volumes with the Expert Partitioner. To fine-tune settings such as the subvolume and snapshot handling for each Btrfs partition, choose Btrfs. For more information about custom partitioning and configuring advanced features, refer to Section 12.1, “Using the YaST Partitioner”.

Warning
Warning: Custom Partitioning on UEFI Machines

A UEFI machine requires an EFI system partition that must be mounted to /boot/efi. This partition must be formatted with the FAT file system.

If an EFI system partition is already present on your system (for example from a previous Windows installation) use it by mounting it to /boot/efi without formatting it.

Warning
Warning: Custom Partitioning and Snapper

By default, SUSE Linux Enterprise Server is set up to support snapshots which provide the ability to do rollbacks of system changes. SUSE Linux Enterprise Server uses Snapper with Btrfs for this feature. Refer to Chapter 7, System Recovery and Snapshot Management with Snapper for details.

Being able to create system snapshots that enable rollbacks requires most of the system directories to be mounted on a single partition. Refer to Section 7.1, “Default Setup” for more information. This also includes /usr and /var. Only directories that are excluded from snapshots (see Section 7.1.2, “Directories That Are Excluded from Snapshots” for a list) may reside on separate partitions. Among others, this list includes /usr/local, /var/log, and /tmp.

If you do not plan to use Snapper for system rollbacks, the partitioning restrictions mentioned above do not apply.

Important
Important: Btrfs on an Encrypted Root Partition

The default partitioning setup suggests the root partition as Btrfs with /boot being a directory. To encrypt the root partition, make sure to use the GPT partition table type instead of the default MSDOS type. Otherwise the GRUB2 boot loader may not have enough space for the second stage loader.

Note
Note: IBM z Systems: Using Minidisks in z/VM

If SUSE Linux Enterprise Server is installed on minidisks in z/VM, which reside on the same physical disk, the access path of the minidisks (/dev/disk/by-id/) is not unique, because it represents the ID of the physical disk. So if two or more minidisks are on the same physical disk, they all have the same ID.

To avoid problems when mounting minidisks, always mount them either by path or by UUID.

Warning
Warning: IBM z Systems: LVM Root File System

If you configure the system with an root file system on LVM or software raid array, you must place /boot on a separate, non-LVM or non-Raid partition, otherwise the system will fail to boot. The recommended size for such a partition is 500 MB and the recommended file system is Ext4.

Note
Note: Supported Software RAID Volumes

Installing to and booting from existing software RAID volumes is supported for Disk Data Format (DDF) volumes and Intel Matrix Storage Manager (IMSM) volumes. IMSM is also known by the following names:

  • Intel Rapid Storage Technology

  • Intel Matrix Storage Technology

  • Intel Application Accelerator / Intel Application Accelerator RAID Edition

Note
Note: Mount Points for FCoE and iSCSI Devices

FCoE and iSCSI devices will appear asynchronously during the boot process. While the initrd guarantees that those devices are set up correctly for the root file system, there are no such guarantees for any other file systems or mount points like /usr. Hence any system mount points like /usr or /var are not supported. To use those devices, ensure correct synchronization of the respective services and devices.

Partitioning
Figure 6.11: Partitioning

6.12 Clock and Time Zone

In this dialog, select your region and time zone. Both are preselected according to the installation language. To change the preselected values, either use the map or the drop-down boxes for Region and Time Zone. When using the map, point the cursor at the rough direction of your region and left-click to zoom. Now choose your country or region by left-clicking. Right-click to return to the world map.

To set up the clock, choose whether the Hardware Clock is Set to UTC. If you run another operating system on your machine, such as Microsoft Windows, it is likely your system uses local time instead. If you run Linux on your machine, set the hardware clock to UTC and have the switch from standard time to daylight saving time performed automatically.

Important
Important: Set the Hardware Clock to UTC

The switch from standard time to daylight saving time (and vice versa) can only be performed automatically when the hardware clock (CMOS clock) is set to UTC. This also applies if you use automatic time synchronization with NTP, because automatic synchronization will only be performed if the time difference between the hardware and system clock is less than 15 minutes.

Since a wrong system time can cause serious problems (missed backups, dropped mail messages, mount failures on remote file systems, etc.), it is strongly recommended to always set the hardware clock to UTC.

Clock and Time Zone
Figure 6.12: Clock and Time Zone

POWER, x86_64 If a network is already configured, you can configure time synchronization with an NTP server. Click Other Settings to either alter the NTP settings or to Manually set the time. See Chapter 24, Time Synchronization with NTP for more information on configuring the NTP service. When finished, click Accept to continue the installation.

POWER, x86_64 If running without NTP configured, consider setting SYSTOHC=no (sysconfig variable) to avoid saving unsynchronized time into the hardware clock.

Note
Note: Time Cannot Be Changed on IBM z Systems

Since the operating system is not allowed to change time and date directly, the Other Settings option is not available on IBM z Systems.

6.13 Create New User

Create a local user in this step. After entering the first name and last name, either accept the proposal or specify a new User name that will be used to log in. Only use lowercase letters (a-z), digits (0-9) and the characters . (dot), - (hyphen) and _ (underscore). Special characters, umlauts and accented characters are not allowed.

Finally, enter a password for the user. Re-enter it for confirmation (to ensure that you did not type something else by mistake). To provide effective security, a password should be at least six characters long and consist of uppercase and lowercase letters, number and special characters (7-bit ASCII). Umlauts or accented characters are not allowed. Passwords you enter are checked for weakness. When entering a password that is easy to guess (such as a dictionary word or a name) you will see a warning. It is a good security practice to use strong passwords.

Important
Important: User Name and Password

Remember both your user name and the password because they are needed each time you log in to the system.

If you install SUSE Linux Enterprise Server on a machine with one or more existing Linux installations, YaST allows you to import user data such as user names and passwords. Select Import User Data from a Previous Installation and then Choose Users for import.

If you do not want to configure any local users (for example when setting up a client on a network with centralized user authentication), skip this step by choosing Next and confirming the warning. Network user authentication can be configured at any time later in the installed system; refer to Chapter 16, Managing Users with YaST for instructions.

Create New User
Figure 6.13: Create New User

Two additional options are available:

Use this Password for System Administrator

If checked, the same password you have entered for the user will be used for the system administrator root. This option is suitable for stand-alone workstations or machines in a home network that are administrated by a single user. When not checked, you are prompted for a system administrator password in the next step of the installation workflow (see Section 6.14, “Password for the System Administrator root).

Automatic Login

This option automatically logs the current user in to the system when it starts. This is mainly useful if the computer is operated by only one user. For automatic login to work, the option must be explicitly enabled.

6.13.1 Expert Settings

Click Change in the Create User dialog to import users from a previous installation (if present). Also change the password encryption type in this dialog.

The default authentication method is Local (/etc/passwd). If a former version of SUSE Linux Enterprise Server or another system using /etc/passwd is detected, you may import local users. To do so, check Read User Data from a Previous Installation and click Choose. In the next dialog, select the users to import and finish with OK.

By default the passwords are encrypted with the SHA-512 hash function. Changing this method is not recommended unless needed for compatibility reasons.

6.14 Password for the System Administrator root

If you have not chosen Use this Password for System Administrator in the previous step, you will be prompted to enter a password for the System Administrator root. Otherwise this configuration step is skipped.

root is the name of the superuser, or the administrator of the system. Unlike regular users, root has unlimited rights to change the system configuration, install programs, and set up new hardware. If users forget their passwords or have other problems with the system, root can help. The root account should only be used for system administration, maintenance, and repair. Logging in as root for daily work is rather risky: a single mistake could lead to irretrievable loss of system files.

For verification purposes, the password for root must be entered twice. Do not forget the root password. After having been entered, this password cannot be retrieved.

Password for the System Administrator root
Figure 6.14: Password for the System Administrator root
Tip
Tip: Passwords and Keyboard Layout

It is recommended to only use characters that are available on an English keyboard. In case of a system error or when you need to start your system in rescue mode a localized keyboard might not be available.

The root password can be changed any time later in the installed system. To do so run YaST and start Security and Users › User and Group Management.

Important
Important: The root User

The user root has all the permissions needed to make changes to the system. To carry out such tasks, the root password is required. You cannot carry out any administrative tasks without this password.

6.15 Installation Settings

On the last step before the real installation takes place, you can alter installation settings suggested by the installer. To modify the suggestions, click the respective headline. After having made changes to a particular setting, you are always returned to the Installation Settings window, which is updated accordingly.

Installation Settings
Figure 6.15: Installation Settings

6.15.1 Software

SUSE Linux Enterprise Server contains several software patterns for various application purposes. Click Software to open the Software Selection and System Tasks screen where you can modify the pattern selection according to your needs. Select a pattern from the list and see a description in the right-hand part of the window. Each pattern contains several software packages needed for specific functions (for example Web and LAMP server or a print server). For a more detailed selection based on software packages to install, select Details to switch to the YaST Software Manager.

You can also install additional software packages or remove software packages from your system at any later time with the YaST Software Manager. For more information, refer to Chapter 13, Installing or Removing Software.

Software Selection and System Tasks
Figure 6.16: Software Selection and System Tasks
Note
Note: Graphical Desktop

By default SUSE Linux Enterprise Server is installed with X Window and the GNOME desktop environment. If you do not need X Window, deselect the two respective patterns in the Software Selection and System Tasks screen. As an alternative to GNOME, the light-weight window manager IceWM can be installed. Select Details from the Software Selection and System Tasks screen and search for icewm.

Tip
Tip: IBM z Systems: Hardware Cryptography Support

The hardware cryptography stack is not installed by default. To install it, select System z HW crypto support in the Software Selection and System Tasks screen.

Tip
Tip: Adding Secondary Languages

The language you selected with the first step of the installation will be used as the primary (default) language for the system. You can add secondary languages from within the Software dialog by choosing Details › View › Languages.

6.15.2 Booting

The installer proposes a boot configuration for your system. Other operating systems found on your computer, such as Microsoft Windows or other Linux installations, will automatically be detected and added to the boot loader. However, SUSE Linux Enterprise Server will be booted by default. Normally, you can leave these settings unchanged. If you need a custom setup, modify the proposal according to your needs. For information, see Section 12.3, “Configuring the Boot Loader with YaST”.

Important
Important: Software RAID 1

Booting a configuration where /boot resides on a software RAID 1 device is supported, but it requires to install the boot loader into the MBR (Boot Loader Location › Boot from Master Boot Record). Having /boot on software RAID devices with a level other than RAID 1 is not supported. Also see Chapter 8, Configuring Software RAID for the Root Partition.

6.15.3 Firewall and SSH

By default SuSEFirewall2 is enabled on all configured network interfaces. To globally disable the firewall for this computer, click Disable (not recommended).

Note
Note: Firewall Settings

If the firewall is activated, all interfaces are configured to be in the External Zone, where all ports are closed by default, ensuring maximum security. The only port you can open during the installation is port 22 (SSH), to allow remote access. All other services requiring network access (such as FTP, Samba, Web server, etc.) will only work after having adjusted the firewall settings. Refer to Chapter 15, Masquerading and Firewalls for more information.

To enable remote access via the secure shell (SSH), make sure the SSH service is enabled and the SSH port is open.

Tip
Tip: Existing SSH Host Keys

If you install SUSE Linux Enterprise Server on a machine with one or more existing Linux installations, the installation routine imports the SSH host key with the most recent access time from an existing installation by default. See also Section 6.15.7, “Import SSH Host Keys and Configuration.

If you are performing a remote administration over VNC, you can also specify whether the machine should be accessible via VNC after the installation. Note that enabling VNC also requires you to set the Default systemd Target to graphical.

6.15.4 Kdump

Using Kdump, you can save a dump of the kernel (in case of a crash) to analyze what went wrong. Use this dialog to enable and configure Kdump. Find detailed information at Chapter 17, Kexec and Kdump.

6.15.5 IBM z Systems: Blacklist Devices

To save memory, all channels for devices currently not in use are blacklisted by default (each channel that is not blacklisted occupies approximately 50 KB of memory). To configure additional hardware in the installed system using channels that are currently blacklisted, run the respective YaST module to enable the respective channels first.

To disable blacklisting, click disable.

6.15.6 Default systemd Target

SUSE Linux Enterprise Server can boot into two different targets (formerly known as runlevels). The graphical target starts a display manager, whereas the multi-user target starts the command line interface.

The default target is graphical. In case you have not installed the X Window System patterns, you need to change it to multi-user. If the system should be accessible via VNC, you need to choose graphical.

6.15.7 Import SSH Host Keys and Configuration

If an existing Linux installation on your computer was detected, YaST will import the most recent SSH host key found in /etc/ssh by default, optionally including other files in the directory as well. This makes it possible to reuse the SSH identity of the existing installation, avoiding the REMOTE HOST IDENTIFICATION HAS CHANGED warning on the first connection. Note that this item is not shown in the installation summary if YaST has not discovered any other installations.

Import SSH Host Keys and Configuration
Figure 6.17: Import SSH Host Keys and Configuration
I would like to import SSH keys from a previous install:

Select this option if you want to import the SSH host key and optionally the configuration of an installed system. You can select the installation to import from in the option list below.

Import SSH Configuration

Enable this to copy other files in /etc/ssh to the installed system in addition to the host keys.

6.15.8 System Information

This screen lists all the hardware information the installer could obtain about your computer. When opened for the first time, the hardware detection is started. Depending on your system, this may take some time. Select any item in the list and click Details to see detailed information about the selected item. Use Save to File to save a detailed list to either the local file system or a removable device.

Advanced users can also change the PCI ID Setup and kernel settings by choosing Kernel Settings. A screen with two tabs opens:

PCI ID Setup

Each kernel driver contains a list of device IDs of all devices it supports. If a new device is not in any driver's database, the device is treated as unsupported, even if it can be used with an existing driver. You can add PCI IDs to a device driver here. Only advanced users should attempt to do so.

To add an ID, click Add and select whether to Manually enter the data, or whether to choose from a list. Enter the required data. The SysFS Dir is the directory name from /sys/bus/pci/drivers—if empty, the driver name is used as the directory name. Existing entries can be managed with Edit and Delete.

Kernel Settings

Change the Global I/O Scheduler here. If Not Configured is chosen, the default setting for the respective architecture will be used. This setting can also be changed at any time later from the installed system. Refer to Chapter 12, Tuning I/O Performance for details on I/O tuning.

Also activate the Enable SysRq Keys here. These keys will let you issue basic commands (such as rebooting the system or writing kernel dumps) in case the system crashes. Enabling these keys is recommended when doing kernel development. Refer to https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html for details.

6.16 Performing the Installation

After configuring all installation settings, click Install in the Installation Settings window to start the installation. Some software may require a license confirmation. If your software selection includes such software, license confirmation dialogs are displayed. Click Accept to install the software package. When not agreeing to the license, click I Disagree and the software package will not be installed. In the dialog that follows, confirm with Install again.

The installation usually takes between 15 and 30 minutes, depending on the system performance and the selected software scope. After having prepared the hard disk and having saved and restored the user settings, the software installation starts. During this procedure a slide show introduces the features of SUSE Linux Enterprise Server. Choose Details to switch to the installation log or Release Notes to read important up-to-date information that was not available when the manuals were printed.

After the software installation has completed, the system reboots into the new installation where you can log in. To customize the system configuration or to install additional software packages, start YaST.

Note
Note: One-Stage Installation

Starting with SUSE Linux Enterprise Server 12 the system installation and basic configuration including the network setup is done in a single stage. After having rebooted into the installed system, you can log in and start using the system. To fine-tune the setup, to configure services or to install additional software, start YaST.

6.16.1 IBM z Systems: IPLing the Installed System

YaST usually reboots into the installed system on the IBM z Systems platform. Exceptions are installations where the boot loader resides on an FCP device in environments with LPAR on a machine older than z196 or with z/VM older than release 5.4. The boot loader gets written to a separate partition mounted as /boot/zipl/.

In cases where an automatic reboot is not possible, YaST will show a dialog containing information about from which device to do an IPL. Accept the shutdown option and perform an IPL after the shutdown. The procedure varies according to the type of installation:

LPAR Installation

In the IBM z Systems HMC, select Load, select Clear, then enter the loading address (the address of the device containing the /boot/zipl directory with the boot loader). If using a zFCP disk as the boot device, choose Load from SCSI and specify the load address of your FCP adapter plus WWPN and LUN of the boot device. Now start the loading process.

z/VM Installation

Log in to the VM guest (see Example 4.1, “Configuration of a z/VM Directory” for the configuration) as LINUX1 and proceed to IPL the installed system:

IPL 151 CLEAR

151 is an example address of the DASD boot device, replace this value with the correct address.

If using a zFCP disk as the boot device, specify both the zFCP WWPN and LUN of the boot device before initiating the IPL. The parameter length is limited to eight characters. Longer numbers must be separated by spaces:

SET LOADDEV PORT 50050763 00C590A9 LUN 50010000 00000000

Finally, initiate the IPL:

IPL FC00

FC00 is an example address of the zFCP adapter, replace this value with the correct address.

KVM Guest Installation

After the installation has finished, the virtual machine is shut down. At this point, log in to the KVM host, edit the virtual machine's description file and restart it to IPL into the installed system:

  1. Log in to the KVM host.

  2. Edit the domain XML file by running

    virsh edit s12-1

    and remove the following lines:

      <!-- Boot kernel - remove 3 lines after successfull installation -->
      <kernel>/var/lib/libvirt/images/s12-kernel.boot</kernel>
      <initrd>/var/lib/libvirt/images/s12-initrd.boot</initrd>
      <cmdline>linuxrcstderr=/dev/console</cmdline>
  3. Restart the VM Guest to IPL into the installed system:

    virsh start s12-1 --console
Note
Note: cio_ignore Is Disabled for KVM Installations

The kernel parameter cio_ignore prevents the kernel from looking at all the available hardware devices. However, for KVM guests, the hypervisor already takes care to only provide access to the correct devices. Therefore cio_ignore is disabled by default when installing a KVM guest (for z/VM and LPAR installations it is activated by default).

6.16.2 IBM z Systems: Connecting to the Installed System

After IPLing the system, establish a connection via VNC, SSH, or X to log in to the installed system. Using either VNC or SSH is recommended. To customize the system configuration or to install additional software packages, start YaST.

6.16.2.1 Using VNC to Connect

A message in the 3270 terminal asks you to connect to the Linux system using a VNC client. However, this message is easily missed, because it is mixed with kernel messages and the terminal process might quit before you notice the message. If nothing happens for five minutes, try to initiate a connection to the Linux system using a VNC viewer.

6.16.2.2 Using SSH to Connect

A message in the 3270 terminal asks you to connect to the Linux system with an SSH client. This message is easily missed, however, because it is mixed with kernel messages and the terminal process might quit before you become aware of the message.

When the message appears, use SSH to log in to the Linux system as root. If the connection is denied or times out, wait for the login timeout to expire, then try again (this time depends on server settings).

6.16.2.3 Using X to Connect

When IPLing the installed system, make sure that the X server used for the first phase of the installation is up and still available before booting from the DASD. YaST opens on this X server to finish the installation. Complications may arise if the system is booted up but unable to connect to the X server in a timely fashion.

7 Cloning Disk Images

  • Filename: deployment_image.xml
  • ID: cha.deployment.clone_image

If SUSE Linux Enterprise Server is installed in a virtualized environment, cloning an existing installation may be the fastest way to deploy further machines. SUSE Linux Enterprise Server provides a script to clean up configuration that is unique to each installation. With the introduction of systemd, unique system identifiers are used and set in different locations and files. Therefore, cloning is no longer the recommended way to build system images. Images can be created with KIWI, see https://doc.opensuse.org/projects/kiwi/doc/

To clone disks of machines, refer to the documentation of your virtualization environment.

7.1 Cleaning Up Unique System Identifiers

Warning
Warning: Important Configuration Loss

Executing the following procedure permanently deletes important system configuration data. If the source system for the clone is used in production, run the clean up script on the cloned image.

To clean all unique system identifiers, execute the following procedure before or after cloning a disk image. If run on the clone, this procedure needs to be run on each clone. Therefore, we recommend to create a golden image that is not used in production and only serves as a source for new clones. The golden image is already cleaned up and clones can be used immediately.

The clone-master-clean-up command for example removes:

  • Swap files

  • Zypper repositories

  • SSH host and client keys

  • Temporary directories, like /tmp/*

  • Postfix data

  • HANA firewall script

  • systemd journal

  1. Use zypper to install clone-master-clean-up:

    root # zypper install clone-master-clean-up
  2. Configure the behavior of clone-master-clean-up by editing the /etc/sysconfig/clone-master-clean-up. This configuration file defines if users with a UID larger than 1000, the /etc/sudoers file, Zypper repositories and Btrfs snapshots should be removed.

  3. Remove existing configuration and unique identifiers by running the script:

    root # clone-master-clean-up

Part III Setting Up an Installation Server

8 Setting Up the Server Holding the Installation Sources

SUSE® Linux Enterprise Server can be installed in different ways. Apart from the usual media installation covered in Chapter 6, Installation with YaST, you can choose from various network-based approaches or even opt for an unattended installation of SUSE Linux Enterprise Server.

9 Preparing the Boot of the Target System

SUSE® Linux Enterprise Server can be installed in different ways. Apart from the usual media installation covered in Chapter 6, Installation with YaST, you can choose from various network-based approaches or even take a completely hands-off approach to the installation of SUSE Linux Enterprise Serve…

8 Setting Up the Server Holding the Installation Sources

  • Filename: deployment_installserver.xml
  • ID: cha.deployment.instserver

SUSE® Linux Enterprise Server can be installed in different ways. Apart from the usual media installation covered in Chapter 6, Installation with YaST, you can choose from various network-based approaches or even opt for an unattended installation of SUSE Linux Enterprise Server.

Each method is introduced by means of two short checklists: one listing the prerequisites for this method and the other illustrating the basic procedure. More detail is then provided for all the techniques used in these installation scenarios.

Note
Note: Terminology

In the following sections, the system to hold your new SUSE Linux Enterprise Server installation is called target system or installation target. The term repository (previously called installation source) is used for all sources of installation data. This includes physical media, such as CD and DVD, and network servers distributing the installation data in your network.

Depending on the operating system of the machine used as the network installation source for SUSE Linux Enterprise Server, there are several options for the server configuration. The easiest way to set up an installation server is to use YaST on SUSE Linux Enterprise Server or openSUSE.

Tip
Tip: Installation Server Operating System

You can even use a Microsoft Windows machine as the installation server for your Linux deployment. See Section 8.5, “Managing an SMB Repository” for details.

8.1 Setting Up an Installation Server Using YaST

YaST offers a graphical tool for creating network repositories. It supports HTTP, FTP, and NFS network installation servers.

  1. Log in as root to the machine that should act as installation server.

  2. Start YaST › Miscellaneous › Installation Server.

  3. Select the repository type (HTTP, FTP, or NFS). The selected service is started automatically every time the system starts. If a service of the selected type is already running on your system and you want to configure it manually for the server, deactivate the automatic configuration of the server service with Do Not Configure Any Network Services. In both cases, define the directory in which the installation data should be made available on the server.

  4. Configure the required repository type. This step relates to the automatic configuration of server services. It is skipped when automatic configuration is deactivated.

    Define an alias for the root directory of the FTP or HTTP server on which the installation data should be found. The repository will later be located under ftp://Server-IP/Alias/Name (FTP) or under http://Server-IP/Alias/Name (HTTP). Name stands for the name of the repository, which is defined in the following step. If you selected NFS in the previous step, define wild cards and export options. The NFS server will be accessible under nfs://Server-IP/Name. Details of NFS and exports can be found in Chapter 27, Sharing File Systems with NFS.

    Tip
    Tip: Firewall Settings

    Make sure that the firewall settings of your server system allow traffic on the ports for HTTP, NFS, and FTP. If they currently do not, enable Open Port in Firewall or check Firewall Details first.

  5. Configure the repository. Before the installation media are copied to their destination, define the name of the repository (ideally, an easily remembered abbreviation of the product and version). YaST allows providing ISO images of the media instead of copies of the installation DVDs. If you want this, activate the relevant check box and specify the directory path under which the ISO files can be found locally. Depending on the product to distribute using this installation server, it might be necessary to add additional media, such as service pack DVDs as extra repositories. To announce your installation server in the network via OpenSLP, activate the appropriate option.

    Tip
    Tip: Announcing the Repository

    Consider announcing your repository via OpenSLP if your network setup supports this option. This saves you from entering the network installation path on every target machine. The target systems are booted using the SLP boot option and find the network repository without any further configuration. For details on this option, refer to Section 10.2, “Booting the Target System for Installation”.

  6. Configuring extra repositories. YaST follows a specific naming convention to configure add-on CDs or service pack CDs repositories. Configuration is accepted only if the repository name of the add-on CDs starts with the repository name of the installation media, In other words, if you chose SLES12SP1 as repository name for DVD1 than you should chose SLES12SP1addon repository name for DVD2. Same applies to SDK CDs.

  7. Upload the installation data. The most lengthy step in configuring an installation server is copying the actual installation media. Insert the media in the sequence requested by YaST and wait for the copying procedure to end. When the sources have been fully copied, return to the overview of existing repositories and close the configuration by selecting Finish.

    Your installation server is now fully configured and ready for service. It is automatically started every time the system is started. No further intervention is required. You only need to configure and start this service correctly by hand if you have deactivated the automatic configuration of the selected network service with YaST as an initial step.

To deactivate a repository, select the repository to remove then select Delete. The installation data are removed from the system. To deactivate the network service, use the respective YaST module.

If your installation server needs to provide the installation data for more than one product of the product version, start the YaST installation server module and select Add in the overview of existing repositories to configure the new repository.

8.2 Setting Up an NFS Repository Manually

Setting up an NFS source for installation is done in two main steps. In the first step, create the directory structure holding the installation data and copy the installation media over to this structure. Second, export the directory holding the installation data to the network.

To create a directory to hold the installation data, proceed as follows:

  1. Log in as root.

  2. Create a directory that will later hold all installation data and change into this directory. For example:

    root # mkdir /srv/install/PRODUCT/PRODUCTVERSION
    root # cd /srv/install/PRODUCT/PRODUCTVERSION

    Replace PRODUCT with an abbreviation of the product name and PRODUCTVERSION with a string that contains the product name and version.

  3. For each DVD contained in the media kit execute the following commands:

    1. Copy the entire content of the installation DVD into the installation server directory:

      root # cp -a /media/PATH_TO_YOUR_DVD_DRIVE .

      Replace PATH_TO_YOUR_DVD_DRIVE with the actual path under which your DVD drive is addressed. Depending on the type of drive used in your system, this can be cdrom, cdrecorder, dvd, or dvdrecorder.

    2. Rename the directory to the DVD number:

      root # mv PATH_TO_YOUR_DVD_DRIVE DVDX

      Replace X with the actual number of your DVD.

On SUSE Linux Enterprise Server, you can export the repository with NFS using YaST. Proceed as follows:

  1. Log in as root.

  2. Start YaST › Network Services › NFS Server.

  3. Select Start and Open Port in Firewall and click Next.

  4. Select Add Directory and browse for the directory containing the installation sources, in this case, PRODUCTVERSION.

  5. Select Add Host and enter the host names of the machines to which to export the installation data. Instead of specifying host names here, you could also use wild cards, ranges of network addresses, or the domain name of your network. Enter the appropriate export options or leave the default, which works fine in most setups. For more information about the syntax used in exporting NFS shares, read the exports man page.

  6. Click Finish. The NFS server holding the SUSE Linux Enterprise Server repository is automatically started and integrated into the boot process.

If you prefer manually exporting the repository via NFS instead of using the YaST NFS Server module, proceed as follows:

  1. Log in as root.

  2. Open the file /etc/exports and enter the following line:

    /PRODUCTVERSION *(ro,root_squash,sync)

    This exports the directory /PRODUCTVERSION to any host that is part of this network or to any host that can connect to this server. To limit the access to this server, use netmasks or domain names instead of the general wild card *. Refer to the export man page for details. Save and exit this configuration file.

  3. To add the NFS service to the list of servers started during system boot, execute the following commands:

    root # systemctl enable nfsserver
  4. Start the NFS server with systemctl start nfsserver. If you need to change the configuration of your NFS server later, modify the configuration file and restart the NFS daemon with systemctl restart nfsserver.

Announcing the NFS server via OpenSLP makes its address known to all clients in your network.

  1. Log in as root.

  2. Create the /etc/slp.reg.d/install.suse.nfs.reg configuration file with the following lines:

    # Register the NFS Installation Server
    service:install.suse:nfs://$HOSTNAME/PATH_TO_REPOSITORY/DVD1,en,65535
    description=NFS Repository

    Replace PATH_TO_REPOSITORY with the actual path to the installation source on your server.

  3. Start the OpenSLP daemon with systemctl start slpd.

For more information about OpenSLP, refer to the package documentation located under /usr/share/doc/packages/openslp/ or refer to Chapter 30, SLP. More Information about NFS, refer to Chapter 27, Sharing File Systems with NFS.

8.3 Setting Up an FTP Repository Manually

Creating an FTP repository is very similar to creating an NFS repository. An FTP repository can be announced over the network using OpenSLP as well.

  1. Create a directory holding the installation sources as described in Section 8.2, “Setting Up an NFS Repository Manually”.

  2. Configure the FTP server to distribute the contents of your installation directory:

    1. Log in as root and install the package vsftpd using the YaST software management.

    2. Enter the FTP server root directory:

      root # cd /srv/ftp
    3. Create a subdirectory holding the installation sources in the FTP root directory:

      root # mkdir REPOSITORY

      Replace REPOSITORY with the product name.

    4. Mount the contents of the installation repository into the change root environment of the FTP server:

      root # mount --bind PATH_TO_REPOSITORY /srv/ftp/REPOSITORY

      Replace PATH_TO_REPOSITORY and REPOSITORY with values matching your setup. If you need to make this permanent, add it to /etc/fstab.

    5. Start vsftpd with vsftpd.

  3. Announce the repository via OpenSLP, if this is supported by your network setup:

    1. Create the /etc/slp.reg.d/install.suse.ftp.reg configuration file with the following lines:

      # Register the FTP Installation Server
      service:install.suse:ftp://$HOSTNAME/REPOSITORY/DVD1,en,65535
      description=FTP Repository

      Replace REPOSITORY with the actual name to the repository directory on your server. The service: line should be entered as one continuous line.

    2. Start the OpenSLP daemon with systemctl start slpd.

Tip
Tip: Configuring an FTP Server with YaST

If you prefer using YaST instead of manually configuring the FTP installation server, refer to Chapter 32, Setting Up an FTP Server with YaST for more information on how to use the YaST FTP server module.

8.4 Setting Up an HTTP Repository Manually

Creating an HTTP repository is very similar to creating an NFS repository. An HTTP repository can be announced over the network using OpenSLP as well.

  1. Create a directory holding the installation sources as described in Section 8.2, “Setting Up an NFS Repository Manually”.

  2. Configure the HTTP server to distribute the contents of your installation directory:

    1. Install the Web server Apache as described in Section 31.1.2, “Installation”.

    2. Enter the root directory of the HTTP server (/srv/www/htdocs) and create the subdirectory that will hold the installation sources:

      root # mkdir REPOSITORY

      Replace REPOSITORY with the product name.

    3. Create a symbolic link from the location of the installation sources to the root directory of the Web server (/srv/www/htdocs):

      root # ln -s /PATH_TO_REPOSITORY/srv/www/htdocs/REPOSITORY
    4. Modify the configuration file of the HTTP server (/etc/apache2/default-server.conf) to make it follow symbolic links. Replace the following line:

      Options None

      with

      Options Indexes FollowSymLinks
    5. Reload the HTTP server configuration using systemctl reload apache2.

  3. Announce the repository via OpenSLP, if this is supported by your network setup:

    1. Create the /etc/slp.reg.d/install.suse.http.reg configuration file with the following lines:

      # Register the HTTP Installation Server
      service:install.suse:http://$HOSTNAME/REPOSITORY/DVD1/,en,65535
      description=HTTP Repository

      Replace REPOSITORY with the actual path to the repository on your server. The service: line should be entered as one continuous line.

    2. Start the OpenSLP daemon using systemctl start slpd.

8.5 Managing an SMB Repository

Using SMB, you can import the installation sources from a Microsoft Windows server and start your Linux deployment even with no Linux machine around.

To set up an exported Windows Share holding your SUSE Linux Enterprise Server repository, proceed as follows:

  1. Log in to your Windows machine.

  2. Create a new directory that will hold the entire installation tree and name it INSTALL, for example.

  3. Export this share according the procedure outlined in your Windows documentation.

  4. Enter this share and create a subdirectory, called PRODUCT. Replace PRODUCT with the actual product name.

  5. Enter the INSTALL/PRODUCT directory and copy each DVD to a separate directory, such as DVD1 and DVD2.

To use an SMB mounted share as a repository, proceed as follows:

  1. Boot the installation target.

  2. Select Installation.

  3. Press F4 for a selection of the repository.

  4. Choose SMB and enter the Windows machine's name or IP address, the share name (INSTALL/PRODUCT/DVD1, in this example), user name, and password. The syntax looks like this:

    smb://workdomain;user:password@server/INSTALL/DVD1

    After you press Enter, YaST starts and you can perform the installation.

8.6 Using ISO Images of the Installation Media on the Server

Instead of copying physical media into your server directory manually, you can also mount the ISO images of the installation media into your installation server and use them as a repository. To set up an HTTP, NFS or FTP server that uses ISO images instead of media copies, proceed as follows:

  1. Download the ISO images and save them to the machine to use as the installation server.

  2. Log in as root.

  3. Choose and create an appropriate location for the installation data, as described in Section 8.2, “Setting Up an NFS Repository Manually”, Section 8.3, “Setting Up an FTP Repository Manually”, or Section 8.4, “Setting Up an HTTP Repository Manually”.

  4. Create subdirectories for each DVD.

  5. To mount and unpack each ISO image to the final location, issue the following command:

    root # mount -o loop PATH_TO_ISO PATH_TO_REPOSITORY/PRODUCT/MEDIUMX

    Replace PATH_TO_ISO with the path to your local copy of the ISO image, PATH_TO_REPOSITORY with the source directory of your server, PRODUCT with the product name, and MEDIUMX with the type (CD or DVD) and number of media you are using.

  6. Repeat the previous step to mount all ISO images needed for your product.

  7. Start your installation server as usual, as described in Section 8.2, “Setting Up an NFS Repository Manually”, Section 8.3, “Setting Up an FTP Repository Manually”, or Section 8.4, “Setting Up an HTTP Repository Manually”.

To automatically mount the ISO images at boot time, add the respective mount entries to /etc/fstab. An entry according to the previous example would look like the following:

PATH_TO_ISO PATH_TO_REPOSITORY/PRODUCTMEDIUM auto loop

9 Preparing the Boot of the Target System

  • Filename: deployment_prep_boot.xml
  • ID: cha.deployment.prep_boot

SUSE® Linux Enterprise Server can be installed in different ways. Apart from the usual media installation covered in Chapter 6, Installation with YaST, you can choose from various network-based approaches or even take a completely hands-off approach to the installation of SUSE Linux Enterprise Server.

The examples use NFS for serving the installation data. If you want to use FTP, SMB or HTTP, see Chapter 8, Setting Up the Server Holding the Installation Sources.

Note
Note: Terminology

In the following sections, the system to hold your new SUSE Linux Enterprise Server installation is called target system or installation target. The term repository (previously called installation source) is used for all sources of installation data. This includes physical media, such as CD and DVD, and network servers distributing the installation data in your network.

This section covers the configuration tasks needed in complex boot scenarios. It contains ready-to-apply configuration examples for DHCP, PXE boot, TFTP, and Wake on LAN.

The examples assume that the DHCP, TFTP and NFS server reside on the same machine with the IP 192.168.1.1. All services can reside on different machines without any problems. Make sure to change the IP addresses as required.

9.1 Setting Up a DHCP Server

In addition to providing automatic address allocation to your network clients, the DHCP server announces the IP address of the TFTP server and the file that needs to be pulled in by the installation routines on the target machine. The file that has to be loaded depends on the architecture of the target machine and whether legacy BIOS or UEFI boot is used.

  1. Log in as root to the machine hosting the DHCP server.

  2. Enable the DHCP server by executing systemctl enable dhcpd.

  3. Append the following lines to a subnet configuration of your DHCP server's configuration file located under /etc/dhcpd.conf:

    # The following lines are optional
    option domain-name "my.lab";
    option domain-name-servers 192.168.1.1;
    option routers 192.168.1.1;
    option ntp-servers 192.168.1.1;
    ddns-update-style none;
    default-lease-time 3600;
    
    # The following lines are required
    option arch code 93 = unsigned integer 16; # RFC4578
    subnet 192.168.1.0 netmask 255.255.255.0 {
     next-server 192.168.1.1;
     range 192.168.1.100 192.168.1.199;
     default-lease-time 3600;
     max-lease-time 3600;
     if option arch = 00:07 or option arch = 00:09 {
       filename "/EFI/x86/grub.efi";
     }
     else if option arch = 00:0b {
       filename "/EFI/aarch64/bootaa64.efi";
     }
     else  {
       filename "/BIOS/x86/pxelinux.0";
     }
    }

    This configuration example uses the subnet 192.168.1.0/24 with the DHCP, DNS and gateway on the server with the IP 192.168.1.1. Make sure that all used IP addresses are changed according to your network layout. For more information about the options available in dhcpd.conf, refer to the dhcpd.conf manual page.

  4. Restart the DHCP server by executing systemctl restart dhcpd.

If you plan to use SSH for the remote control of a PXE and Wake on LAN installation, specify the IP address DHCP should provide to the installation target. To achieve this, modify the above mentioned DHCP configuration according to the following example:

group {
 host test {
   hardware ethernet MAC_ADDRESS;
   fixed-address IP_ADDRESS;
   }
}

The host statement introduces the host name of the installation target. To bind the host name and IP address to a specific host, you must know and specify the system's hardware (MAC) address. Replace all the variables used in this example with the actual values that match your environment.

After restarting the DHCP server, it provides a static IP to the host specified, enabling you to connect to the system via SSH.

9.2 Setting Up a TFTP Server

If using a SUSE based installation, you may use YaST to set up a TFTP Server. Alternatively, set it up manually. The TFTP server delivers the boot image to the target system after it boots and sends a request for it.

9.2.1 Setting Up a TFTP Server Using YaST

  1. Log in as root.

  2. Start YaST › Network Services › TFTP Server and install the requested package.

  3. Click Enable to make sure that the server is started and included in the boot routines. No further action from your side is required to secure this. xinetd starts tftpd at boot time.

  4. Click Open Port in Firewall to open the appropriate port in the firewall running on your machine. If there is no firewall running on your server, this option is not available.

  5. Click Browse to browse for the boot image directory. The default directory /srv/tftpboot is created and selected automatically.

  6. Click Finish to apply your settings and start the server.

9.2.2 Setting Up a TFTP Server Manually

  1. Log in as root and install the packages tftp and xinetd.

  2. Modify the configuration of xinetd located under /etc/xinetd.d to make sure that the TFTP server is started on boot:

    1. If it does not exist, create a file called tftp under this directory with touch tftp. Then run chmod 755 tftp.

    2. Open the file tftp and add the following lines:

      service tftp
      {
              socket_type            = dgram
              protocol               = udp
              wait                   = yes
              user                   = root
              server                 = /usr/sbin/in.tftpd
              server_args            = -s /srv/tftpboot
              disable                = no
      }
    3. Save the file and restart xinetd with systemctl restart xinetd.

9.3 Installing Files on TFTP Server

The following procedures describe how to prepare the server for target machines with UEFI and BIOS on x86 architectures with 32 and 64 bits. The prepared structure also already provides for AArch64 systems.

9.3.1 Preparing the Structure

In this procedure, replace OS_VERSION and SP_VERSION with the used operating system and service pack version. For example, use sles12 and sp3.

  1. Create a structure in /srv/tftpboot to support the various options.

    root # mkdir -p /srv/tftpboot/BIOS/x86
    root # mkdir -p /srv/tftpboot/EFI/x86/boot
    root # mkdir -p /srv/tftpboot/EFI/aarch64/boot
    root # mkdir -p /srv/install/x86/OS_VERSION/SP_VERSION/cd1
    root # mkdir -p /srv/install/aarch64/OS_VERSION/SP_VERSION/cd1
  2. Download the DVD ISO images of SUSE Linux Enterprise Server 12 SP3 from the SUSE Web site for all architectures you need.

  3. Mount the ISO files as described in Section 8.6, “Using ISO Images of the Installation Media on the Server”. To have the files available after a reboot, create an entry in /etc/fstab. For a standard installation, only DVD 1 is required.

    root # mount -o loop PATH_TO_ISO /srv/install/ARCH/OS_VERSION/SP_VERSION/cd1/

    Repeat this step for all required architectures and replace ARCH with x86 or aarch64 and PATH_TO_ISO with the path to the corresponding ISO file.

  4. Copy the kernel, initrd and message files required for x86 BIOS and UEFI boot to the appropriate location.

    root # cd /srv/install/x86/OS_version/SP_version/cd1/boot/x86_64/loader/
    root # cp -a linux initrd message /srv/tftpboot/BIOS/x86/
  5. Ensure that the path /srv/install is available via NFS. For details, see Section 8.2, “Setting Up an NFS Repository Manually”.

9.3.2 BIOS Files for x86

  1. Copy pxelinux.0 into the TFTP folder and prepare a subfolder for the configuration file.

    root # cp /usr/share/syslinux/pxelinux.0 /srv/tftpboot/BIOS/x86/
    root # mkdir /srv/tftpboot/BIOS/x86/pxelinux.cfg
  2. Create /srv/tftpboot/BIOS/x86/pxelinux.cfg/default and add the following lines:

    default install
    
    # hard disk
    label harddisk
     localboot -2
    # install
    label install
     kernel linux
     append initrd=initrd install=nfs://192.168.1.1:/srv/install/x86/OS_version/SP_version/cd1
    
    display message
    implicit 0
    prompt 1
    timeout 5
  3. Edit the file /srv/tftpboot/BIOS/x86/message to reflect the default file you just edited.

    Welcome to the Installer Environment!
    
    To start the installation enter 'install' and press <return>.
    
    Available boot options:
     harddisk   - Boot from Hard Disk (this is default)
     install    - Installation

9.3.3 UEFI Files for x86

In this procedure replace OS_version and SP_version with the used operating system and service pack version. For example use sles12 and sp3.

  1. Copy all required grub2 files for UEFI booting.

    root # cd /srv/install/x86/OS_version/SP_version/cd1/EFI/BOOT
    root # cp -a bootx64.efi grub.efi MokManager.efi /srv/tftpboot/EFI/x86/
  2. Copy the kernel and initrd files to the directory structure.

    root # cd /srv/install/x86/OS_version/SP_version/cd1/boot/x86_64/loader/
    root # cp -a linux initrd /srv/tftpboot/EFI/x86/boot
  3. Create the file /srv/tftpboot/EFI/x86/grub.cfg with at least the following content:

    set timeout=5
    menuentry 'Install OS_version SP_version for x86_64' {
      linuxefi /EFI/x86/boot/linux \
       install=nfs://192.168.1.1/srv/install/x86/OS_version/SP_version/cd1
      initrdefi /EFI/x86/boot/initrd
    }

9.3.4 UEFI Files for AArch64

In this procedure replace OS_version and SP_version with the used operating system and service pack version. For example use sles12 and sp3.

  1. This is done in a way very similar to the x86_64 EFI environment. Start by copying the files required for UEFI booting of a grub2-efi environment.

    root # cd /srv/install/aarch64/OS_version/SP_version/cd1/EFI/BOOT
    root # cp -a bootaa64.efi /srv/tftpboot/EFI/aarch64/
  2. Copy the kernel and initrd to the directory structure.

    root # cd /srv/install/aarch64/OS_version/SP_version/cd1/boot/aarch64
    root # cp -a linux initrd /srv/tftpboot/EFI/aarch64/boot
  3. Now create the file /srv/tftpboot/EFI/grub.cfg and add the following content:

    menuentry 'Install OS_version SP_version' {
      linux /EFI/aarch64/boot/linux network=1 usessh=1 sshpassword="suse" \
       install=nfs://192.168.1.1:/srv/install/aarch64/OS_version/SP_version/cd1 \
       console=ttyAMA0,115200n8
      initrd /EFI/aarch64/boot/initrd
    }

    This addition to the configuration file has a few other options to enable the serial console and allow installation via SSH, which is helpful for systems that do not have a standard KVM console interface. You will notice that this is set up for a specific ARM platform.

9.4 PXELINUX Configuration Options

The options listed here are a subset of all the options available for the PXELINUX configuration file.

APPEND OPTIONS

Add one or more options to the kernel command line. These are added for both automatic and manual boots. The options are added at the very beginning of the kernel command line, usually permitting explicitly entered kernel options to override them.

APPEND -

Append nothing. APPEND with a single hyphen as argument in a LABEL section can be used to override a global APPEND.

DEFAULT KERNEL_OPTIONS...

Sets the default kernel command line. If PXELINUX boots automatically, it acts as if the entries after DEFAULT had been typed in at the boot prompt, except the auto option is automatically added, indicating an automatic boot.

If no configuration file exists or no DEFAULT entry is defined in the configuration file, the default is the kernel name linux with no options.

IFAPPEND FLAG

Adds a specific option to the kernel command line depending on the FLAG value. The IFAPPEND option is available only on PXELINUX. FLAG expects a value, described in Table 9.1, “Generated and Added Kernel Command Line Options from IFAPPEND:

Table 9.1: Generated and Added Kernel Command Line Options from IFAPPEND

Argument

Generated Kernel Command Line / Description

1

ip=CLIENT_IP:BOOT_SERVER_IP:GW_IP:NETMASK

The placeholders are replaced based on the input from the DHCP/BOOTP or PXE boot server.

Note, this option is not a substitute for running a DHCP client in the booted system. Without regular renewals, the lease acquired by the PXE BIOS will expire, making the IP address available for reuse by the DHCP server.

2

BOOTIF=MAC_ADDRESS_OF_BOOT_INTERFACE

This option is useful if you want to avoid timeouts when the installation server probes one LAN interface after the other until it gets a reply from a DHCP server. This option allows an initrd program to determine from which interface the system has been booted. linuxrc reads this option and uses this network interface.

4

SYSUUID=SYSTEM_UUID

Adds UUIDs in lowercase hexadecimals, see /usr/share/doc/packages/syslinux/pxelinux.txt

LABEL LABEL KERNEL IMAGE APPEND OPTIONS...

Indicates that if LABEL is entered as the kernel to boot, PXELINUX should instead boot IMAGE and the specified APPEND options should be used instead of the ones specified in the global section of the file (before the first LABEL command). The default for IMAGE is the same as LABEL and, if no APPEND is given, the default is to use the global entry (if any). Up to 128 LABEL entries are permitted.

PXELINUX uses the following syntax:

label MYLABEL
  kernel MYKERNEL
  append MYOPTIONS

Labels are mangled as if they were file names and they must be unique after mangling. For example, the two labels v2.6.30 and v2.6.31 would not be distinguishable under PXELINUX because both mangle to the same DOS file name.

The kernel does not need to be a Linux kernel. It can also be a boot sector or a COMBOOT file.

LOCALBOOT TYPE

On PXELINUX, specifying LOCALBOOT 0 instead of a KERNEL option means invoking this particular label and causes a local disk boot instead of a kernel boot.

Argument

Description

0

Perform a normal boot

4

Perform a local boot with the Universal Network Driver Interface (UNDI) driver still resident in memory

5

Perform a local boot with the entire PXE stack, including the UNDI driver, still resident in memory

All other values are undefined. If you do not know what the UNDI or PXE stacks are, specify 0.

TIMEOUT TIME-OUT

Indicates how long to wait at the boot prompt until booting automatically, in units of 1/10 second. The time-out is canceled when the user types anything on the keyboard, assuming the user will complete the command begun. A time-out of zero disables the time-out completely (this is also the default). The maximum possible time-out value is 35996 (just less than one hour).

PROMPT flag_val

If flag_val is 0, displays the boot prompt only if Shift or Alt is pressed or Caps Lock or Scroll Lock is set (this is the default). If flag_val is 1, always displays the boot prompt.

F2  FILENAME
F1  FILENAME
..etc...
F9  FILENAME
F10 FILENAME

Displays the indicated file on the screen when a function key is pressed at the boot prompt. This can be used to implement preboot online help (presumably for the kernel command line options). For backward compatibility with earlier releases, F10 can be also entered as F0. Note that there is currently no way to bind file names to F11 and F12.

9.5 Preparing the Target System for PXE Boot

Prepare the system's BIOS for PXE boot by including the PXE option in the BIOS boot order.

Warning
Warning: BIOS Boot Order

Do not place the PXE option ahead of the hard disk boot option in the BIOS. Otherwise this system would try to re-install itself every time you boot it.

9.6 Preparing the Target System for Wake on LAN

Wake on LAN (WOL) requires the appropriate BIOS option to be enabled prior to the installation. Also, note down the MAC address of the target system. This data is needed to initiate Wake on LAN.

9.7 Wake on LAN

Wake on LAN allows a machine to be turned on by a special network packet containing the machine's MAC address. Because every machine in the world has a unique MAC identifier, you do not need to worry about accidentally turning on the wrong machine.

Important
Important: Wake on LAN across Different Network Segments

If the controlling machine is not located on the same network segment as the installation target that should be awakened, either configure the WOL requests to be sent as multicasts or remotely control a machine on that network segment to act as the sender of these requests.

Users of SUSE Linux Enterprise Server can use a YaST module called WOL to easily configure Wake on LAN. Users of other versions of SUSE Linux-based operating systems can use a command line tool.

9.8 Wake on LAN with YaST

  1. Log in as root.

  2. Start YaST › Network Services › WOL.

  3. Click Add and enter the host name and MAC address of the target system.

  4. To turn on this machine, select the appropriate entry and click Wake up.

9.9 Booting from CD or USB Drive Instead of PXE

You can also use a CD, DVD or USB drive with a small system image instead of booting via PXE. The necessary files will be loaded via NFS when the kernel and initrd are loaded. A bootable image can be created with mksusecd. This can be useful if the target machine does not support PXE boot.

Install it with sudo zypper in mksusecd. Use the following command to create a bootable ISO image:

tux > mksusecd --create image.iso \
--net=nfs://192.168.1.1:/srv/install/ARCH/OS_VERSION/SP_VERSION/cd1  \
/srv/tftpboot/EFI/ARCH/boot

Replace ARCH with the folder corresponding to the target system architecture. Also replace OS_version and SP_version according to your paths in Section 9.3, “Installing Files on TFTP Server”.

Instead of using an NFS server for the --net option, it is also possible to use an HTTP repository, for example the openSUSE repository:

tux > mksusecd --create image.iso \
--net=http://download.opensuse.org/tumbleweed/repo/oss/suse \
/srv/tftpboot/EFI/ARCH/boot

The image.iso can be written to a DVD or CD, or using dd to a USB stick:

root # dd if=image.iso of=/dev/USB_DEVICE

Replace USB_DEVICE with the device name of your USB stick. Check the device name thoroughly to ensure that you are not accidentally destroying data on another drive.

Part IV Remote Installation

10 Remote Installation

SUSE® Linux Enterprise Server can be installed in different ways. In addition to the usual media installation covered in Chapter 6, Installation with YaST, you can choose from various network-based approaches or even opt for an unattended installation of SUSE Linux Enterprise Server.

10 Remote Installation

  • Filename: deployment_remote.xml
  • ID: cha.deployment.remoteinst

SUSE® Linux Enterprise Server can be installed in different ways. In addition to the usual media installation covered in Chapter 6, Installation with YaST, you can choose from various network-based approaches or even opt for an unattended installation of SUSE Linux Enterprise Server.

Each method is introduced by means of two short checklists: one listing the prerequisites for that method and the other illustrating the basic procedure. More detail is then provided for all the techniques used in these installation scenarios.

Note
Note: Terminology

In the following sections, the system to hold your new SUSE Linux Enterprise Server installation is called target system or installation target. The term repository (previously called installation source) is used for all sources of installation data. This includes physical media, such as CD and DVD, and network servers distributing the installation data in your network.

10.1 Installation Scenarios for Remote Installation

This section introduces the most common installation scenarios for remote installations. For each scenario, carefully check the list of prerequisites and follow the procedure outlined for that scenario. If in need of detailed instructions for a particular step, follow the links provided for each one of them.

10.1.1 Simple Remote Installation via VNC—Static Network Configuration

This type of installation still requires some degree of physical access to the target system to boot for installation. The installation is controlled by a remote workstation using VNC to connect to the installation program. User interaction is required as with the manual installation in Chapter 6, Installation with YaST.

For this type of installation, make sure that the following requirements are met:

  • A repository, either remote or local:

    • Remote repository: NFS, HTTP, FTP, TFTP, or SMB with working network connection.

    • Local repository, for example a DVD.

  • Target system with working network connection.

  • Controlling system with working network connection and VNC viewer software.

  • Physical boot medium (CD, DVD, or flash disk) for booting the target system.

  • Valid static IP addresses already assigned to the repository and the controlling system.

  • Valid static IP address to assign to the target system.

To perform this kind of installation, proceed as follows:

  1. Set up the repository as described in Chapter 8, Setting Up the Server Holding the Installation Sources. Choose an NFS, HTTP, FTP, or TFTP network server. For an SMB repository, refer to Section 8.5, “Managing an SMB Repository”.

  2. Boot the target system using DVD1 of the SUSE Linux Enterprise Server media kit.

  3. When the boot screen of the target system appears, use the boot options prompt to set the appropriate VNC options and the address of the repository. This is described in detail in Section 10.2, “Booting the Target System for Installation”.

    The target system boots to a text-based environment, giving the network address and display number under which the graphical installation environment can be addressed by any VNC viewer application or browser. VNC installations announce themselves over OpenSLP and if the firewall settings permit. They can be found using slptool as described in Procedure 10.1, “Locating VNC installations via OpenSLP”.

  4. On the controlling workstation, open a VNC viewing application or Web browser and connect to the target system as described in Section 10.3.1, “VNC Installation”.

  5. Perform the installation as described in Chapter 6, Installation with YaST. Reconnect to the target system after it reboots for the final part of the installation.

  6. Finish the installation.

10.1.2 Simple Remote Installation via VNC—Dynamic Network Configuration

This type of installation still requires some degree of physical access to the target system to boot for installation. The network configuration is done via DHCP. The installation is controlled from a remote workstation using VNC, but configuration does require user interaction.

For this type of installation, make sure that the following requirements are met:

  • Remote repository: NFS, HTTP, FTP, or SMB with working network connection.

  • Target system with working network connection.

  • Controlling system with working network connection and VNC viewer software.

  • Boot the target system using DVD1 of the SUSE Linux Enterprise Server media kit.

  • Running DHCP server providing IP addresses.

To perform this kind of installation, proceed as follows:

  1. Set up the repository as described in Chapter 8, Setting Up the Server Holding the Installation Sources. Choose an NFS, HTTP, or FTP network server. For an SMB repository, refer to Section 8.5, “Managing an SMB Repository”.

  2. Boot the target system using DVD1 of the SUSE Linux Enterprise Server media kit.

  3. When the boot screen of the target system appears, use the boot options prompt to set the appropriate VNC options and the address of the repository. This is described in detail in Section 10.2, “Booting the Target System for Installation”.

    The target system boots to a text-based environment, giving the network address and display number under which the graphical installation environment can be addressed by any VNC viewer application or browser. VNC installations announce themselves over OpenSLP and if the firewall settings permit. They can be found using slptool as described in Procedure 10.1, “Locating VNC installations via OpenSLP”.

  4. On the controlling workstation, open a VNC viewing application or Web browser and connect to the target system as described in Section 10.3.1, “VNC Installation”.

  5. Perform the installation as described in Chapter 6, Installation with YaST. Reconnect to the target system after it reboots for the final part of the installation.

  6. Finish the installation.

10.1.3 Remote Installation via VNC—PXE Boot and Wake on LAN

This type of installation is completely hands-off. The target machine is started and booted remotely. User interaction is only needed for the actual installation. This approach is suitable for cross-site deployments.

To perform this type of installation, make sure that the following requirements are met:

  • Remote repository: NFS, HTTP, FTP, or SMB with working network connection.

  • TFTP server.

  • Running DHCP server for your network.

  • Target system capable of PXE boot, networking, and Wake on LAN, plugged in and connected to the network.

  • Controlling system with working network connection and VNC viewer software.

To perform this type of installation, proceed as follows:

  1. Set up the repository as described in Chapter 8, Setting Up the Server Holding the Installation Sources. Choose an NFS, HTTP, or FTP network server or configure an SMB repository as described in Section 8.5, “Managing an SMB Repository”.

  2. Set up a TFTP server to hold a boot image that can be pulled by the target system. This is described in Section 9.2, “Setting Up a TFTP Server”.

  3. Set up a DHCP server to provide IP addresses to all machines and reveal the location of the TFTP server to the target system. This is described in Section 9.1, “Setting Up a DHCP Server”.

  4. Prepare the target system for PXE boot. This is described in further detail in Section 9.5, “Preparing the Target System for PXE Boot”.

  5. Initiate the boot process of the target system using Wake on LAN. This is described in Section 9.7, “Wake on LAN”.

  6. On the controlling workstation, open a VNC viewing application or Web browser and connect to the target system as described in Section 10.3.1, “VNC Installation”.

  7. Perform the installation as described in Chapter 6, Installation with YaST. Reconnect to the target system after it reboots for the final part of the installation.

  8. Finish the installation.

10.1.4 Simple Remote Installation via SSH—Static Network Configuration

This type of installation still requires some degree of physical access to the target system to boot for installation and to determine the IP address of the installation target. The installation itself is entirely controlled from a remote workstation using SSH to connect to the installer. User interaction is required as with the regular installation described in Chapter 6, Installation with YaST.

For this type of installation, make sure that the following requirements are met:

  • Remote repository: NFS, HTTP, FTP, or SMB with working network connection.

  • Target system with working network connection.

  • Controlling system with working network connection and working SSH client software.

  • Boot the target system using DVD1 of the SUSE Linux Enterprise Server media kit.

  • Valid static IP addresses already assigned to the repository and the controlling system.

  • Valid static IP address to assign to the target system.

To perform this kind of installation, proceed as follows:

  1. Set up the repository as described in Chapter 8, Setting Up the Server Holding the Installation Sources. Choose an NFS, HTTP, or FTP network server. For an SMB repository, refer to Section 8.5, “Managing an SMB Repository”.

  2. Boot the target system using DVD1 of the SUSE Linux Enterprise Server media kit.

  3. When the boot screen of the target system appears, use the boot options prompt to set the appropriate parameters for network connection, address of the repository, and SSH enablement. This is described in detail in Section 10.2.2, “Using Custom Boot Options”.

    The target system boots to a text-based environment, giving the network address under which the graphical installation environment can be addressed by any SSH client.

  4. On the controlling workstation, open a terminal window and connect to the target system as described in Section 10.3.2.2, “Connecting to the Installation Program”.

  5. Perform the installation as described in Chapter 6, Installation with YaST. Reconnect to the target system after it reboots for the final part of the installation.

  6. Finish the installation.

10.1.5 Simple Remote Installation via SSH—Dynamic Network Configuration

This type of installation still requires some degree of physical access to the target system to boot for installation and determine the IP address of the installation target. The installation is controlled from a remote workstation using SSH , but configuration does require user interaction.

Note
Note: Avoid Lost Connections After the Second Step (Installation)

In the network settings dialog, check the Traditional Method with ifup and avoid NetworkManager. If not, your SSH connection will be lost during installation. Reset the settings to User Controlled with NetworkManager after your installation has finished.

For this type of installation, make sure that the following requirements are met:

  • A repository, either remote or local:

    • Remote repository: NFS, HTTP, FTP, TFTP, or SMB with working network connection.

    • Local repository, for example a DVD.

  • Target system with working network connection.

  • Controlling system with working network connection and working SSH client software.

  • Physical boot medium (CD, DVD, or flash disk) for booting the target system.

  • Running DHCP server providing IP addresses.

To perform this kind of installation, proceed as follows:

  1. Set up the repository source as described in Chapter 8, Setting Up the Server Holding the Installation Sources. Choose an NFS, HTTP, or FTP network server. For an SMB repository, refer to Section 8.5, “Managing an SMB Repository”.

  2. Boot the target system using DVD1 of the SUSE Linux Enterprise Server media kit.

  3. When the boot screen of the target system appears, use the boot options prompt to pass the appropriate parameters for network connection, location of the installation source, and SSH enablement. See Section 10.2.2, “Using Custom Boot Options” for detailed instructions on the use of these parameters.

    The target system boots to a text-based environment, giving you the network address under which the graphical installation environment can be addressed by any SSH client.

  4. On the controlling workstation, open a terminal window and connect to the target system as described in Section 10.3.2.2, “Connecting to the Installation Program”.

  5. Perform the installation as described in Chapter 6, Installation with YaST. Reconnect to the target system after it reboots for the final part of the installation.

  6. Finish the installation.

10.1.6 Remote Installation via SSH—PXE Boot and Wake on LAN

This type of installation is completely hands-off. The target machine is started and booted remotely.

To perform this type of installation, make sure that the following requirements are met:

  • Remote repository: NFS, HTTP, FTP, or SMB with working network connection.

  • TFTP server.

  • Running DHCP server for your network, providing a static IP to the host to install.

  • Target system capable of PXE boot, networking, and Wake on LAN, plugged in and connected to the network.

  • Controlling system with working network connection and SSH client software.

To perform this type of installation, proceed as follows:

  1. Set up the repository as described in Chapter 8, Setting Up the Server Holding the Installation Sources. Choose an NFS, HTTP, or FTP network server. For the configuration of an SMB repository, refer to Section 8.5, “Managing an SMB Repository”.

  2. Set up a TFTP server to hold a boot image that can be pulled by the target system. This is described in Section 9.2, “Setting Up a TFTP Server”.

  3. Set up a DHCP server to provide IP addresses to all machines and reveal the location of the TFTP server to the target system. This is described in Section 9.1, “Setting Up a DHCP Server”.

  4. Prepare the target system for PXE boot. This is described in further detail in Section 9.5, “Preparing the Target System for PXE Boot”.

  5. Initiate the boot process of the target system using Wake on LAN. This is described in Section 9.7, “Wake on LAN”.

  6. On the controlling workstation, start an SSH client and connect to the target system as described in Section 10.3.2, “SSH Installation”.

  7. Perform the installation as described in Chapter 6, Installation with YaST. Reconnect to the target system after it reboots for the final part of the installation.

  8. Finish the installation.

10.2 Booting the Target System for Installation

There are two different ways to customize the boot process for installation apart from those mentioned under Section 9.7, “Wake on LAN” and Section 9.3.1, “Preparing the Structure”. You can either use the default boot options and function keys. Alternatively, you can use the boot options prompt in the installation boot screen to specify desired boot options that the installation kernel may require for the specific hardware.

10.2.1 Using the Default Boot Options

The boot options are described in detail in Chapter 6, Installation with YaST. Generally, selecting Installation starts the installation boot process.

If problems occur, use Installation—ACPI Disabled or Installation—Safe Settings. For more information about troubleshooting the installation process, refer to Section 40.2, “Installation Problems”.

The menu bar at the bottom of the screen offers some advanced functionality needed in some setups. Using the function keys (F1 ... F12), you can specify additional options to pass to the installation routines without having to know the detailed syntax of these parameters (see Section 10.2.2, “Using Custom Boot Options”). A detailed description of the available function keys is available in Section 6.2.2.1, “The Boot Screen on Machines Equipped with Traditional BIOS”.

10.2.2 Using Custom Boot Options

Using the appropriate set of boot options helps simplify your installation procedure. Many parameters can also be configured later using the linuxrc routines, but using the boot options is easier. In some automated setups, the boot options can be provided with initrd or an info file.

The following table lists all installation scenarios mentioned in this chapter with the required parameters for booting and the corresponding boot options. Append all of them in the order they appear in this table to get one boot option string that is handed to the installation routines. For example (all in one line):

install=XXX netdevice=XXX hostip=XXX netmask=XXX vnc=XXX VNCPassword=XXX

Replace all the values XXX in this command with the values appropriate for your setup.

Chapter 6, Installation with YaST

Parameters Needed for Booting.  None

Boot Options.  None needed

Section 10.1.1, “Simple Remote Installation via VNC—Static Network Configuration”
Parameters Needed for Booting
  • Location of the installation server

  • Network device

  • IP address

  • Netmask

  • Gateway

  • VNC enablement

  • VNC password

Boot Options
  • install=(nfs,http,​ftp,smb)://PATH_TO_INSTMEDIA

  • netdevice=NETDEVICE (only needed if several network devices are available)

  • hostip=IP_ADDRESS

  • netmask=NETMASK

  • gateway=IP_GATEWAY

  • vnc=1

  • VNCPassword=PASSWORD

Section 10.1.2, “Simple Remote Installation via VNC—Dynamic Network Configuration”
Parameters Needed for Booting
  • Location of the installation server

  • VNC enablement

  • VNC password

Boot Options
  • install=(nfs,http,​ftp,smb)://PATH_TO_INSTMEDIA

  • vnc=1

  • VNCPassword=PASSWORD

Section 10.1.3, “Remote Installation via VNC—PXE Boot and Wake on LAN”
Parameters Needed for Booting
  • Location of the installation server

  • Location of the TFTP server

  • VNC enablement

  • VNC password

Boot Options.  Not applicable; process managed through PXE and DHCP

Section 10.1.4, “Simple Remote Installation via SSH—Static Network Configuration”
Parameters Needed for Booting
  • Location of the installation server

  • Network device

  • IP address

  • Netmask

  • Gateway

  • SSH enablement

  • SSH password

Boot Options
  • install=(nfs,http,​ftp,smb)://PATH_TO_INSTMEDIA

  • netdevice=NETDEVICE (only needed if several network devices are available)

  • hostip=IP_ADDRESS

  • netmask=NETMASK

  • gateway=IP_GATEWAY

  • ssh=1

  • ssh.password=PASSWORD

Section 10.1.5, “Simple Remote Installation via SSH—Dynamic Network Configuration”
Parameters Needed for Booting
  • Location of the installation server

  • SSH enablement

  • SSH password

Boot Options
  • install=(nfs,http,​ftp,smb)://PATH_TO_INSTMEDIA

  • ssh=1

  • ssh.password=PASSWORD

Section 10.1.6, “Remote Installation via SSH—PXE Boot and Wake on LAN”
  • Location of the installation server

  • Location of the TFTP server

  • SSH enablement

  • SSH password

Boot Options.  Not applicable; process managed through PXE and DHCP

Tip
Tip: More Information about linuxrc Boot Options

Find more information about the linuxrc boot options used for booting a Linux system at http://en.opensuse.org/SDB:Linuxrc.

10.2.2.1 Installing Add-On Products and Driver Updates

SUSE Linux Enterprise Server supports installation of add-on products, such as extensions (for example the SUSE Linux Enterprise High Availability Extension), third-party products as well as drivers or additional software. To automatically install an add-on product when deploying SUSE Linux Enterprise Server remotely, specify the addon=REPOSITORY parameter.

REPOSITORY needs to be a hosted repository that can be read by YaST (YaST2 or YUM (rpm-md)). ISO images are currently not supported.

Tip
Tip: Driver Updates

Driver Updates can be found at http://drivers.suse.com/. Not all driver updates are provided as repositories—some are only available as ISO images and therefore cannot be installed with the addon parameter. Instructions on how to install driver updates via ISO image are available at http://drivers.suse.com/doc/SolidDriver/Driver_Kits.html.

10.3 Monitoring the Installation Process

There are several options for remotely monitoring the installation process. If the appropriate boot options have been specified while booting for installation, either VNC or SSH can be used to control the installation and system configuration from a remote workstation.

10.3.1 VNC Installation

Using any VNC viewer software, you can remotely control the installation of SUSE Linux Enterprise Server from virtually any operating system. This section introduces the setup using a VNC viewer application or a Web browser.

10.3.1.1 Preparing for VNC Installation

To enable VNC on the installation target, specify the appropriate boot options at the initial boot for installation (see Section 10.2.2, “Using Custom Boot Options”). The target system boots into a text-based environment and waits for a VNC client to connect to the installation program.

The installation program announces the IP address and display number needed to connect for installation. If you have physical access to the target system, this information is provided right after the system booted for installation. Enter this data when your VNC client software prompts for it and provide your VNC password.

Because the installation target announces itself via OpenSLP, you can retrieve the address information of the installation target via an SLP browser without the need for any physical contact to the installation itself, provided your network setup and all machines support OpenSLP:

Procedure 10.1: Locating VNC installations via OpenSLP
  1. Run slptool findsrvtypes | grep vnc to get a list of all services offering VNC. The VNC installation targets should be available under a service named YaST.installation.suse.

  2. Run slptool findsrvs YaST.installation.suse to get a list of installations available. Use the IP address and the port (usually 5901) provided with your VNC viewer.

10.3.1.2 Connecting to the Installation Program

To connect to a VNC server (the installation target in this case), start an independent VNC viewer application on any operating system.

Using VNC, you can control the installation of a Linux system from any other operating system, including other Linux flavors, Windows, or macOS.

On a Linux machine, make sure that the package tightvnc is installed. On a Windows machine, install the Windows port of this application, which can be obtained at the TightVNC home page (http://www.tightvnc.com/download.html).

To connect to the installation program running on the target machine, proceed as follows:

  1. Start the VNC viewer.

  2. Enter the IP address and display number of the installation target as provided by the SLP browser or the installation program itself:

    IP_ADDRESS:DISPLAY_NUMBER

    A window opens on your desktop displaying the YaST screens as in a normal local installation.

10.3.2 SSH Installation

Using SSH, you can remotely control the installation of your Linux machine using any SSH client software.

10.3.2.1 Preparing for SSH Installation

In addition to installing the required software package (OpenSSH for Linux and PuTTY for Windows), you need to specify the appropriate boot options to enable SSH for installation. See Section 10.2.2, “Using Custom Boot Options” for details. OpenSSH is installed by default on any SUSE Linux–based operating system.

10.3.2.2 Connecting to the Installation Program

  1. Retrieve the installation target's IP address. If you have physical access to the target machine, take the IP address the installation routine provides in the console after the initial boot. Otherwise take the IP address that has been assigned to this particular host in the DHCP server configuration.

  2. In a command line, enter the following command:

    ssh -X root@
    ip_address_of_target

    Replace IP_ADDRESS_OF_TARGET with the actual IP address of the installation target.

  3. When prompted for a user name, enter root.

  4. When prompted for the password, enter the password that has been set with the SSH boot option. After you have successfully authenticated, a command line prompt for the installation target appears.

  5. Enter yast to launch the installation program. A window opens showing the normal YaST screens as described in Chapter 6, Installation with YaST.

Part V Initial System Configuration

11 Setting Up Hardware Components with YaST

YaST allows you to configure hardware items such as audio hardware, your system keyboard layout or printers.

12 Advanced Disk Setup

Sophisticated system configurations require specific disk setups. All common partitioning tasks can be done with YaST. To get persistent device naming with block devices, use the block devices below /dev/disk/by-id or /dev/disk/by-uuid. Logical Volume Management (LVM) is a disk partitioning scheme t…

13 Installing or Removing Software

Use YaST's software management module to search for software components you want to add or remove. YaST resolves all dependencies for you. To install packages not shipped with the installation media, add additional software repositories to your setup and let YaST manage them. Keep your system up-to-date by managing software updates with the update applet.

14 Installing Modules, Extensions, and Third Party Add-On Products

Modules and extensions add parts or functionality to the system. Modules are fully supported parts of SUSE Linux Enterprise Server with a different life cycle and update timeline. They are a set of packages, have a clearly defined scope and are delivered via online channel only.

Extensions, such as the Workstation Extension or the High Availability Extension, add extra functionality to the system and require an own registration key that is liable for costs. Extensions are delivered via online channel or physical media. Registering at the SUSE Customer Center or a local registration server is a prerequisite for subscribing to the online channels. The Package Hub (Section 14.5, “SUSE Package Hub”) and SUSE Software Development Kit (Section 14.4, “SUSE Software Development Kit (SDK) 12 SP3) extensions are exceptions which do not require a registration key and are not covered by SUSE support agreements.

A list of modules and extensions for your product is available after having registered your system at SUSE Customer Center or a local registration server. If you skipped the registration step during the installation, you can register your system at any time using the SUSE Customer Center Configuration module in YaST. For details, refer to Section 20.9, “Registering Your System”.

Some add-on products are also provided by third parties, for example, binary-only drivers that are needed by certain hardware to function properly. If you have such hardware, refer to the release notes for more information about availability of binary drivers for your system. The release notes are available from http://www.suse.com/releasenotes/, from YaST or from /usr/share/doc/release-notes/ in your installed system.

15 Installing Multiple Kernel Versions

SUSE Linux Enterprise Server supports the parallel installation of multiple kernel versions. When installing a second kernel, a boot entry and an initrd are automatically created, so no further manual configuration is needed. When rebooting the machine, the newly added kernel is available as an additional boot option.

Using this functionality, you can safely test kernel updates while being able to always fall back to the proven former kernel. To do this, do not use the update tools (such as the YaST Online Update or the updater applet), but instead follow the process described in this chapter.

16 Managing Users with YaST

During installation, you could have created a local user for your system. With the YaST module User and Group Management you can add more users or edit existing ones. It also lets you configure your system to authenticate users with a network server.

17 Changing Language and Country Settings with YaST

Working in different countries or having to work in a multilingual environment requires your computer to be set up to support this. SUSE® Linux Enterprise Server can handle different locales in parallel. A locale is a set of parameters that defines the language and country settings reflected in the …

11 Setting Up Hardware Components with YaST

  • Filename: yast2_hw.xml
  • ID: cha.y2.hw
Abstract

YaST allows you to configure hardware items such as audio hardware, your system keyboard layout or printers.

Note
Note: Graphics Card, Monitor, Mouse and Keyboard Settings

Graphics card, monitor, mouse and keyboard can be configured with GNOME tools.

11.1 Setting Up Your System Keyboard Layout

  • Filename: yast2_keymouse.xml
  • ID: cha.y2.hw.keym

The YaST System Keyboard Layout module lets you define the default keyboard layout for the system (also used for the console). Users can modify the keyboard layout in their individual X sessions, using the desktop's tools.

  1. Start the YaST System Keyboard Configuration dialog by clicking Hardware › System Keyboard Layout in YaST. Alternatively, start the module from the command line with sudo yast2 keyboard.

  2. Select the desired Keyboard Layout from the list.

  3. Optionally, you can also define the keyboard repeat rate or keyboard delay rate in the Expert Settings.

  4. Try the selected settings in the Test text box.

  5. If the result is as expected, confirm your changes and close the dialog. The settings are written to /etc/sysconfig/keyboard.

11.2 Setting Up Sound Cards

  • Filename: yast2_sound.xml
  • ID: sec.y2.hw.sound

YaST detects most sound cards automatically and configures them with the appropriate values. To change the default settings, or to set up a sound card that could not be configured automatically, use the YaST sound module. There, you can also set up additional sound cards or switch their order.

To start the sound module, start YaST and click Hardware › Sound. Alternatively, start the Sound Configuration dialog directly by running yast2 sound & as user root from a command line.

The dialog shows all sound cards that were detected.

Procedure 11.1: Configuring Sound Cards

If you have added a new sound card or YaST could not automatically configure an existing sound card, follow the steps below. For configuring a new sound card, you need to know your sound card vendor and model. If in doubt, refer to your sound card documentation for the required information. For a reference list of sound cards supported by ALSA with their corresponding sound modules, see http://www.alsa-project.org/main/index.php/Matrix:Main.

During configuration, you can choose between the following setup options:

Quick Automatic Setup

You are not required to go through any of the further configuration steps—the sound card is configured automatically. You can set the volume or any options you want to change later.

Normal Setup

Allows you to adjust the output volume and play a test sound during the configuration.

Advanced setup with possibility to change options

For experts only. Allows you to customize all parameters of the sound card.

Important
Important: Advanced Configuration

Only use this option if you know exactly what you are doing. Otherwise leave the parameters untouched and use the normal or the automatic setup options.

  1. Start the YaST sound module.

  2. To configure a detected, but Not Configured sound card, select the respective entry from the list and click Edit.

    To configure a new sound card, click Add. Select your sound card vendor and model and click Next.

  3. Choose one of the setup options and click Next.

  4. If you have chosen Normal Setup, you can now Test your sound configuration and make adjustments to the volume. You should start at about ten percent volume to avoid damage to your hearing or the speakers.

  5. If all options are set according to your wishes, click Next.

    The Sound Configuration dialog shows the newly configured or modified sound card.

  6. To remove a sound card configuration that you no longer need, select the respective entry and click Delete.

  7. Click OK to save the changes and leave the YaST sound module.

Procedure 11.2: Modifying Sound Card Configurations
  1. To change the configuration of an individual sound card (for experts only!), select the sound card entry in the Sound Configuration dialog and click Edit.

    This takes you to the Sound Card Advanced Options where you can fine-tune several parameters. For more information, click Help.

  2. To adjust the volume of an already configured sound card or to test the sound card, select the sound card entry in the Sound Configuration dialog and click Other. Select the respective menu item.

    Note
    Note: YaST Mixer

    The YaST mixer settings provide only basic options. They are intended for troubleshooting (for example, if the test sound is not audible). Access the YaST mixer settings from Other › Volume. For everyday use and fine-tuning of sound options, use the mixer applet provided by your desktop or the alsasound command line tool.

  3. For playback of MIDI files, select Other › Start Sequencer.

  4. When a supported sound card is detected, you can install SoundFonts for playback of MIDI files:

    1. Insert the original driver CD-ROM into your CD or DVD drive.

    2. Select Other › Install SoundFonts to copy SF2 SoundFonts™ to your hard disk. The SoundFonts are saved in the directory /usr/share/sfbank/creative/.

  5. If you have configured more than one sound card in your system you can adjust the order of your sound cards. To set a sound card as primary device, select the sound card in the Sound Configuration and click Other › Set as the Primary Card. The sound device with index 0 is the default device and thus used by the system and the applications.

  6. By default, SUSE Linux Enterprise Server uses the PulseAudio sound system. It is an abstraction layer that helps to mix multiple audio streams, bypassing any restrictions the hardware may have. To enable or disable the PulseAudio sound system, click Other › PulseAudio Configuration. If enabled, PulseAudio daemon is used to play sounds. Disable PulseAudio Support to use something else system-wide.

The volume and configuration of all sound cards are saved when you click OK and leave the YaST sound module. The mixer settings are saved to the file /etc/asound.state. The ALSA configuration data is appended to the end of the file /etc/modprobe.d/sound and written to /etc/sysconfig/sound.

11.3 Setting Up a Printer

  • Filename: yast2_printer.xml
  • ID: sec.y2.hw.print

YaST can be used to configure a local printer connected to your machine via USB and to set up printing with network printers. It is also possible to share printers over the network. Further information about printing (general information, technical details, and troubleshooting) is available in Chapter 17, Printer Operation.

In YaST, click Hardware › Printer to start the printer module. By default it opens in the Printer Configurations view, displaying a list of all printers that are available and configured. This is especially useful when having access to a lot of printers via the network. From here you can also Print a Test Page and configure printers.

Note
Note: Starting CUPS

To be able to print from your system, CUPS must run. In case it is not running, you are asked to start it. Answer with Yes, or you cannot configure printing. In case CUPS is not started at boot time, you will also be asked to enable this feature. It is recommended to say Yes, otherwise CUPS would need to be started manually after each reboot.

11.3.1 Configuring Printers

Usually a USB printer is automatically detected. There are two possible reasons it is not automatically detected:

  • The USB printer is switched off.

  • The communication between printer and computer is not possible. Check the cable and the plugs to make sure that the printer is properly connected. If this is the case, the problem may not be printer-related, but rather a USB-related problem.

Configuring a printer is a three-step process: specify the connection type, choose a driver, and name the print queue for this setup.

For many printer models, several drivers are available. When configuring the printer, YaST defaults to those marked recommended as a general rule. Normally it is not necessary to change the driver. However, if you want a color printer to print only in black and white, you can use a driver that does not support color printing. If you experience performance problems with a PostScript printer when printing graphics, try to switch from a PostScript driver to a PCL driver (provided your printer understands PCL).

If no driver for your printer is listed, try to select a generic driver with an appropriate standard language from the list. Refer to your printer's documentation to find out which language (the set of commands controlling the printer) your printer understands. If this does not work, refer to Section 11.3.1.1, “Adding Drivers with YaST” for another possible solution.

A printer is never used directly, but always through a print queue. This ensures that simultaneous jobs can be queued and processed one after the other. Each print queue is assigned to a specific driver, and a printer can have multiple queues. This makes it possible to set up a second queue on a color printer that prints black and white only, for example. Refer to Section 17.1, “The CUPS Workflow” for more information about print queues.

Procedure 11.3: Adding a New Printer
  1. Start the YaST printer module with Hardware › Printer.

  2. In the Printer Configurations screen click Add.

  3. If your printer is already listed under Specify the Connection, proceed with the next step. Otherwise, try to Detect More or start the Connection Wizard.

  4. In the text box under Find and Assign a Driver enter the vendor name and the model name and click Search for.

  5. Choose a driver that matches your printer. It is recommended to choose the driver listed first. If no suitable driver is displayed:

    1. Check your search term

    2. Broaden your search by clicking Find More

    3. Add a driver as described in Section 11.3.1.1, “Adding Drivers with YaST”

  6. Specify the Default paper size.

  7. In the Set Arbitrary Name field, enter a unique name for the print queue.

  8. The printer is now configured with the default settings and ready to use. Click OK to return to the Printer Configurations view. The newly configured printer is now visible in the list of printers.

11.3.1.1 Adding Drivers with YaST

Not all printer drivers available for SUSE Linux Enterprise Server are installed by default. If no suitable driver is available in the Find and Assign a Driver dialog when adding a new printer install a driver package containing drivers for your printers:

Procedure 11.4: Installing Additional Driver Packages
  1. Start the YaST printer module with Hardware › Printer.

  2. In the Printer Configurations screen, click Add.

  3. In the Find and Assign a Driver section, click Driver Packages.

  4. Choose one or more suitable driver packages from the list. Do not specify the path to a printer description file.

  5. Choose OK and confirm the package installation.

  6. To directly use these drivers, proceed as described in Procedure 11.3, “Adding a New Printer”.

PostScript printers do not need printer driver software. PostScript printers need only a PostScript Printer Description (PPD) file which matches the particular model. PPD files are provided by the printer manufacturer.

If no suitable PPD file is available in the Find and Assign a Driver dialog when adding a PostScript printer install a PPD file for your printer:

Several sources for PPD files are available. It is recommended to first try additional driver packages that are shipped with SUSE Linux Enterprise Server but not installed by default (see below for installation instructions). If these packages do not contain suitable drivers for your printer, get PPD files directly from your printer vendor or from the driver CD of a PostScript printer. For details, see Section 17.8.2, “No Suitable PPD File Available for a PostScript Printer”. Alternatively, find PPD files at http://www.linuxfoundation.org/collaborate/workgroups/openprinting/database/databaseintro, the OpenPrinting.org printer database. When downloading PPD files from OpenPrinting, keep in mind that it always shows the latest Linux support status, which is not necessarily met by SUSE Linux Enterprise Server.

Procedure 11.5: Adding a PPD file for PostScript Printers
  1. Start the YaST printer module with Hardware › Printer.

  2. In the Printer Configurations screen, click Add.

  3. In the Find and Assign a Driver section, click Driver Packages.

  4. Enter the full path to the PPD file into the text box under Make a Printer Description File Available.

  5. Click OK to return to the Add New Printer Configuration screen.

  6. To directly use this PPD file, proceed as described in Procedure 11.3, “Adding a New Printer”.

11.3.1.2 Editing a Local Printer Configuration

By editing an existing configuration for a printer you can change basic settings such as connection type and driver. It is also possible to adjust the default settings for paper size, resolution, media source, etc. You can change identifiers of the printer by altering the printer description or location.

  1. Start the YaST printer module with Hardware › Printer.

  2. In the Printer Configurations screen, choose a local printer configuration from the list and click Edit.

  3. Change the connection type or the driver as described in Procedure 11.3, “Adding a New Printer”. This should only be necessary in case you have problems with the current configuration.

  4. Optionally, make this printer the default by checking Default Printer.

  5. Adjust the default settings by clicking All Options for the Current Driver. To change a setting, expand the list of options by clicking the relative + sign. Change the default by clicking an option. Apply your changes with OK.

11.3.2 Configuring Printing via the Network with YaST

Network printers are not detected automatically. They must be configured manually using the YaST printer module. Depending on your network setup, you can print to a print server (CUPS, LPD, SMB, or IPX) or directly to a network printer (preferably via TCP). Access the configuration view for network printing by choosing Printing via Network from the left pane in the YaST printer module.

11.3.2.1 Using CUPS

In a Linux environment CUPS is usually used to print via the network. The simplest setup is to only print via a single CUPS server which can directly be accessed by all clients. Printing via more than one CUPS server requires a running local CUPS daemon that communicates with the remote CUPS servers.

Important
Important: Browsing Network Print Queues

CUPS servers announce their print queues over the network either via the traditional CUPS browsing protocol or via Bonjour/DND-SD. Clients need to be able to browse these lists, so users can select specific printers to send their print jobs to. To be able to browse network print queues, the service cups-browsed provided by the package cups-filters-cups-browsed must run on all clients that print via CUPS servers. cups-browsed is started automatically when configuring network printing with YaST.

In case browsing does not work after having started cups-browsed, the CUPS server(s) probably announce the network print queues via Bonjour/DND-SD. In this case you need to additionally install the package avahi and start the associated service with sudo systemctl start avahi-daemon on all clients.

Procedure 11.6: Printing via a Single CUPS Server
  1. Start the YaST printer module with Hardware › Printer.

  2. From the left pane, launch the Print via Network screen.

  3. Check Do All Your Printing Directly via One Single CUPS Server and specify the name or IP address of the server.

  4. Click Test Server to make sure you have chosen the correct name or IP address.

  5. Click OK to return to the Printer Configurations screen. All printers available via the CUPS server are now listed.

Procedure 11.7: Printing via Multiple CUPS Servers
  1. Start the YaST printer module with Hardware › Printer.

  2. From the left pane, launch the Print via Network screen.

  3. Check Accept Printer Announcements from CUPS Servers.

  4. Under General Settings specify which servers to use. You may accept connections from all networks available or from specific hosts. If you choose the latter option, you need to specify the host names or IP addresses.

  5. Confirm by clicking OK and then Yes when asked to start a local CUPS server. After the server has started YaST will return to the Printer Configurations screen. Click Refresh list to see the printers detected by now. Click this button again, in case more printer are to be available.

11.3.2.2 Using Print Servers other than CUPS

If your network offers print services via print servers other than CUPS, start the YaST printer module with Hardware › Printer and launch the Print via Network screen from the left pane. Start the Connection Wizard and choose the appropriate Connection Type. Ask your network administrator for details on configuring a network printer in your environment.

11.3.3 Sharing Printers Over the Network

Printers managed by a local CUPS daemon can be shared over the network and so turn your machine into a CUPS server. Usually you share a printer by enabling CUPS' so-called browsing mode. If browsing is enabled, the local print queues are made available on the network for listening to remote CUPS daemons. It is also possible to set up a dedicated CUPS server that manages all print queues and can directly be accessed by remote clients. In this case it is not necessary to enable browsing.

Procedure 11.8: Sharing Printers
  1. Start the YaST printer module with Hardware › Printer.

  2. Launch the Share Printers screen from the left pane.

  3. Select Allow Remote Access. Also check For computers within the local network and enable browsing mode by also checking Publish printers by default within the local network.

  4. Click OK to restart the CUPS server and to return to the Printer Configurations screen.

  5. Regarding CUPS and firewall settings, see http://en.opensuse.org/SDB:CUPS_and_SANE_Firewall_settings.

12 Advanced Disk Setup

  • Filename: advanced_disksetup.xml
  • ID: cha.advdisk

Sophisticated system configurations require specific disk setups. All common partitioning tasks can be done with YaST. To get persistent device naming with block devices, use the block devices below /dev/disk/by-id or /dev/disk/by-uuid. Logical Volume Management (LVM) is a disk partitioning scheme that is designed to be much more flexible than the physical partitioning used in standard setups. Its snapshot functionality enables easy creation of data backups. Redundant Array of Independent Disks (RAID) offers increased data integrity, performance, and fault tolerance. SUSE Linux Enterprise Server also supports multipath I/O (see Chapter 17, Managing Multipath I/O for Devices for details). There is also the option to use iSCSI as a networked disk (read more about iSCSI in Chapter 14, Mass Storage over IP Networks: iSCSI).

12.1 Using the YaST Partitioner

  • Filename: yast2_manpart.xml
  • ID: sec.yast2.i_y2_part_expert

With the expert partitioner, shown in Figure 12.1, “The YaST Partitioner”, manually modify the partitioning of one or several hard disks. You can add, delete, resize, and edit partitions, or access the soft RAID, and LVM configuration.

Warning
Warning: Repartitioning the Running System

Although it is possible to repartition your system while it is running, the risk of making a mistake that causes data loss is very high. Try to avoid repartitioning your installed system and always do a complete backup of your data before attempting to do so.

The YaST Partitioner
Figure 12.1: The YaST Partitioner
Tip
Tip: IBM z Systems: Device Names

IBM z Systems recognizes only DASD and SCSI hard disks. IDE hard disks are not supported. This is why these devices appear in the partition table as dasda or sda for the first recognized device.

All existing or suggested partitions on all connected hard disks are displayed in the list of Available Storage in the YaST Expert Partitioner dialog. Entire hard disks are listed as devices without numbers, such as /dev/sda (or /dev/dasda). Partitions are listed as parts of these devices, such as /dev/sda1 (or /dev/dasda1, respectively). The size, type, encryption status, file system, and mount point of the hard disks and their partitions are also displayed. The mount point describes where the partition appears in the Linux file system tree.

Several functional views are available on the left hand System View. These views can be used to collect information about existing storage configurations, configure functions (like RAID, Volume Management, Crypt Files), and view file systems with additional features, such as Btrfs, NFS, or TMPFS.

If you run the expert dialog during installation, any free hard disk space is also listed and automatically selected. To provide more disk space to SUSE® Linux Enterprise Server, free the needed space starting from the bottom toward the top of the list (starting from the last partition of a hard disk toward the first).

12.1.1 Partition Types

Tip
Tip: IBM z Systems: Hard Disks

On IBM z Systems platforms, SUSE Linux Enterprise Server supports SCSI hard disks and DASDs (direct access storage devices). While SCSI disks can be partitioned as described below, DASDs can have no more than three partition entries in their partition tables.

Every hard disk has a partition table with space for four entries. Every entry in the partition table corresponds to a primary partition or an extended partition. Only one extended partition entry is allowed, however.

A primary partition simply consists of a continuous range of cylinders (physical disk areas) assigned to a particular operating system. With primary partitions you would be limited to four partitions per hard disk, because more do not fit in the partition table. This is why extended partitions are used. Extended partitions are also continuous ranges of disk cylinders, but an extended partition may be divided into logical partitions itself. Logical partitions do not require entries in the partition table. In other words, an extended partition is a container for logical partitions.

If you need more than four partitions, create an extended partition as the fourth partition (or earlier). This extended partition should occupy the entire remaining free cylinder range. Then create multiple logical partitions within the extended partition. The maximum number of logical partitions is 63, independent of the disk type. It does not matter which types of partitions are used for Linux. Primary and logical partitions both function normally.

Tip
Tip: GPT Partition Table

If you need to create more than 4 primary partitions on one hard disk, you need to use the GPT partition type. This type removes the primary partitions number restriction, and supports partitions bigger than 2 TB as well.

To use GPT, run the YaST Partitioner, click the relevant disk name in the System View and choose Expert › Create New Partition Table › GPT.

12.1.2 Creating a Partition

To create a partition from scratch select Hard Disks and then a hard disk with free space. The actual modification can be done in the Partitions tab:

  1. Select Add and specify the partition type (primary or extended). Create up to four primary partitions or up to three primary partitions and one extended partition. Within the extended partition, create several logical partitions (see Section 12.1.1, “Partition Types”).

  2. Specify the size of the new partition. You can either choose to occupy all the free unpartitioned space, or enter a custom size.

  3. Select the file system to use and a mount point. YaST suggests a mount point for each partition created. To use a different mount method, like mount by label, select Fstab Options. For more information on supported file systems, see root.

  4. Specify additional file system options if your setup requires them. This is necessary, for example, if you need persistent device names. For details on the available options, refer to Section 12.1.3, “Editing a Partition”.

  5. Click Finish to apply your partitioning setup and leave the partitioning module.

    If you created the partition during installation, you are returned to the installation overview screen.

12.1.2.1 Btrfs Partitioning

The default file system for the root partition is Btrfs (see Chapter 7, System Recovery and Snapshot Management with Snapper and Chapter 1, Overview of File Systems in Linux for more information on Btrfs). The root file system is the default subvolume and it is not listed in the list of created subvolumes. As a default Btrfs subvolume, it can be mounted as a normal file system.

Important
Important: Btrfs on an Encrypted Root Partition

The default partitioning setup suggests the root partition as Btrfs with /boot being a directory. To encrypt the root partition encrypted, make sure to use the GPT partition table type instead of the default MSDOS type. Otherwise the GRUB2 boot loader may not have enough space for the second stage loader.

It is possible to create snapshots of Btrfs subvolumes—either manually, or automatically based on system events. For example when making changes to the file system, zypper invokes the snapper command to create snapshots before and after the change. This is useful if you are not satisfied with the change zypper made and want to restore the previous state. As snapper invoked by zypper creates snapshots of the root file system by default, it makes sense to exclude specific directories from being included into snapshots. This is the reason why YaST suggests creating the following separate subvolumes.

/boot/grub2/i386-pc, /boot/grub2/x86_64-efi, /boot/grub2/powerpc-ieee1275, /boot/grub2/s390x-emu

A rollback of the boot loader configuration is not supported. The directories listed above are architecture-specific. The first two directories are present on AMD64/Intel 64 machines, the latter two on IBM POWER and on IBM z Systems, respectively.

/home

If /home does not reside on a separate partition, it is excluded to avoid data loss on rollbacks.

/opt, /var/opt

Third-party products usually get installed to /opt. It is excluded to avoid uninstalling these applications on rollbacks.

/srv

Contains data for Web and FTP servers. It is excluded to avoid data loss on rollbacks.

/tmp, /var/tmp, /var/cache, /var/crash

All directories containing temporary files and caches are excluded from snapshots.

/usr/local

This directory is used when manually installing software. It is excluded to avoid uninstalling these installations on rollbacks.

/var/lib/libvirt/images

The default location for virtual machine images managed with libvirt. Excluded to ensure virtual machine images are not replaced with older versions during a rollback. By default, this subvolume is created with the option no copy on write.

/var/lib/mailman, /var/spool

Directories containing mails or mail queues are excluded to avoid a loss of mails after a rollback.

/var/lib/named

Contains zone data for the DNS server. Excluded from snapshots to ensure a name server can operate after a rollback.

/var/lib/mariadb, /var/lib/mysql, /var/lib/pgqsl

These directories contain database data. By default, these subvolumes are created with the option no copy on write.

/var/log

Log file location. Excluded from snapshots to allow log file analysis after the rollback of a broken system.

Tip
Tip: Size of Btrfs Partition

Since saved snapshots require more disk space, it is recommended to reserve enough space for Btrfs. Suggested size for a root Btrfs partition with default subvolumes is 20GB.

12.1.2.1.1 Managing Btrfs Subvolumes using YaST

Subvolumes of a Btrfs partition can be now managed with the YaST Expert partitioner module. You can add new or remove existing subvolumes.

Procedure 12.1: Btrfs Subvolumes with YaST
  1. Start the YaST Expert Partitioner with System › Partitioner.

  2. Choose Btrfs in the left System View pane.

  3. Select the Btrfs partition whose subvolumes you need to manage and click Edit.

  4. Click Subvolume Handling. You can see a list off all existing subvolumes of the selected Btrfs partition. You can notice several @/.snapshots/xyz/snapshot entries—each of these subvolumes belongs to one existing snapshot.

  5. Depending on whether you want to add or remove subvolumes, do the following:

    1. To remove a subvolume, select it from the list of Exisitng Subvolumes and click Remove.

    2. To add a new subvolume, enter its name to the New Subvolume text box and click Add new.

      Btrfs Subvolumes in YaST Partitioner
      Figure 12.2: Btrfs Subvolumes in YaST Partitioner
  6. Confirm with OK and Finish.

  7. Leave the partitioner with Finish.

12.1.3 Editing a Partition

When you create a new partition or modify an existing partition, you can set various parameters. For new partitions, the default parameters set by YaST are usually sufficient and do not require any modification. To edit your partition setup manually, proceed as follows:

  1. Select the partition.

  2. Click Edit to edit the partition and set the parameters:

    File System ID

    Even if you do not want to format the partition at this stage, assign it a file system ID to ensure that the partition is registered correctly. Typical values are Linux, Linux swap, Linux LVM, and Linux RAID.

    File System

    To change the partition file system, click Format Partition and select file system type in the File System list.

    SUSE Linux Enterprise Server supports several types of file systems. Btrfs is the Linux file system of choice for the root partition because of its advanced features. It supports copy-on-write functionality, creating snapshots, multi-device spanning, subvolumes, and other useful techniques. XFS, Ext3 and JFS are journaling file systems. These file systems can restore the system very quickly after a system crash, using write processes logged during the operation. Ext2 is not a journaling file system, but it is adequate for smaller partitions because it does not require much disk space for management.

    The default file system for the root partition is Btrfs. The default file system for additional partitions is XFS.

    Swap is a special format that allows the partition to be used as a virtual memory. Create a swap partition of at least 256 MB. However, if you use up your swap space, consider adding more memory to your system instead of adding more swap space.

    Warning
    Warning: Changing the File System

    Changing the file system and reformatting partitions irreversibly deletes all data from the partition.

    For details on the various file systems, refer to Storage Administration Guide.

    Encrypt Device

    If you activate the encryption, all data is written to the hard disk in encrypted form. This increases the security of sensitive data, but reduces the system speed, as the encryption takes some time to process. More information about the encryption of file systems is provided in Chapter 11, Encrypting Partitions and Files.

    Mount Point

    Specify the directory where the partition should be mounted in the file system tree. Select from YaST suggestions or enter any other name.

    Fstab Options

    Specify various parameters contained in the global file system administration file (/etc/fstab). The default settings should suffice for most setups. You can, for example, change the file system identification from the device name to a volume label. In the volume label, use all characters except / and space.

    To get persistent devices names, use the mount option Device ID, UUID or LABEL. In SUSE Linux Enterprise Server, persistent device names are enabled by default.

    Note
    Note: IBM z Systems: Mounting by Path

    Since mounting by ID causes problems on IBM z Systems when using disk-to-disk copying for cloning purposes, devices are mounted by path in /etc/fstab on IBM z Systems by default.

    If you prefer to mount the partition by its label, you need to define one in the Volume label text entry. For example, you could use the partition label HOME for a partition intended to mount to /home.

    If you intend to use quotas on the file system, use the mount option Enable Quota Support. This must be done before you can define quotas for users in the YaST User Management module. For further information on how to configure user quota, refer to Section 16.3.4, “Managing Quotas”.

  3. Select Finish to save the changes.

Note
Note: Resize File Systems

To resize an existing file system, select the partition and use Resize. Note, that it is not possible to resize partitions while mounted. To resize partitions, unmount the relevant partition before running the partitioner.

12.1.4 Expert Options

After you select a hard disk device (like sda) in the System View pane, you can access the Expert menu in the lower right part of the Expert Partitioner window. The menu contains the following commands:

Create New Partition Table

This option helps you create a new partition table on the selected device.

Warning
Warning: Creating a New Partition Table

Creating a new partition table on a device irreversibly removes all the partitions and their data from that device.

Clone This Disk

This option helps you clone the device partition layout (but not the data) to other available disk devices.

12.1.5 Advanced Options

After you select the host name of the computer (the top-level of the tree in the System View pane), you can access the Configure menu in the lower right part of the Expert Partitioner window. The menu contains the following commands:

Configure iSCSI

To access SCSI over IP block devices, you first need to configure iSCSI. This results in additionally available devices in the main partition list.

Configure Multipath

Selecting this option helps you configure the multipath enhancement to the supported mass storage devices.

12.1.6 More Partitioning Tips

The following section includes a few hints and tips on partitioning that should help you make the right decisions when setting up your system.

Tip
Tip: Cylinder Numbers

Note, that different partitioning tools may start counting the cylinders of a partition with 0 or with 1. When calculating the number of cylinders, you should always use the difference between the last and the first cylinder number and add one.

12.1.6.1 Using swap

Swap is used to extend the available physical memory. It is then possible to use more memory than physical RAM available. The memory management system of kernels before 2.4.10 needed swap as a safety measure. Then, if you did not have twice the size of your RAM in swap, the performance of the system suffered. These limitations no longer exist.

Linux uses a page called Least Recently Used (LRU) to select pages that might be moved from memory to disk. Therefore, running applications have more memory available and caching works more smoothly.

If an application tries to allocate the maximum allowed memory, problems with swap can arise. There are three major scenarios to look at:

System with no swap

The application gets the maximum allowed memory. All caches are freed, and thus all other running applications are slowed. After a few minutes, the kernel's out-of-memory kill mechanism activates and kills the process.

System with medium sized swap (128 MB–512 MB)

At first, the system slows like a system without swap. After all physical RAM has been allocated, swap space is used as well. At this point, the system becomes very slow and it becomes impossible to run commands from remote. Depending on the speed of the hard disks that run the swap space, the system stays in this condition for about 10 to 15 minutes until the out-of-memory kill mechanism resolves the issue. Note that you will need a certain amount of swap if the computer needs to perform a suspend to disk. In that case, the swap size should be large enough to contain the necessary data from memory (512 MB–1GB).

System with lots of swap (several GB)

It is better to not have an application that is out of control and swapping excessively in this case. If you use such application, the system will need many hours to recover. In the process, it is likely that other processes get timeouts and faults, leaving the system in an undefined state, even after terminating the faulty process. In this case, do a hard machine reboot and try to get it running again. Lots of swap is only useful if you have an application that relies on this feature. Such applications (like databases or graphics manipulation programs) often have an option to directly use hard disk space for their needs. It is advisable to use this option instead of using lots of swap space.

If your system is not out of control, but needs more swap after some time, it is possible to extend the swap space online. If you prepared a partition for swap space, add this partition with YaST. If you do not have a partition available, you can also use a swap file to extend the swap. Swap files are generally slower than partitions, but compared to physical RAM, both are extremely slow so the actual difference is negligible.

Procedure 12.2: Adding a Swap File Manually

To add a swap file in the running system, proceed as follows:

  1. Create an empty file in your system. For example, if you want to add a swap file with 128 MB swap at /var/lib/swap/swapfile, use the commands:

    mkdir -p /var/lib/swap
    dd if=/dev/zero of=/var/lib/swap/swapfile bs=1M count=128
  2. Initialize this swap file with the command

    mkswap /var/lib/swap/swapfile
    Note
    Note: Changed UUID for Swap Partitions when Formatting via mkswap

    Do not reformat existing swap partitions with mkswap if possible. Reformatting with mkswap will change the UUID value of the swap partition. Either reformat via YaST (will update /etc/fstab) or adjust /etc/fstab manually.

  3. Activate the swap with the command

    swapon /var/lib/swap/swapfile

    To disable this swap file, use the command

    swapoff /var/lib/swap/swapfile
  4. Check the current available swap spaces with the command

    cat /proc/swaps

    Note that at this point, it is only temporary swap space. After the next reboot, it is no longer used.

  5. To enable this swap file permanently, add the following line to /etc/fstab:

    /var/lib/swap/swapfile swap swap defaults 0 0

12.1.7 Partitioning and LVM

From the Expert partitioner, access the LVM configuration by clicking the Volume Management item in the System View pane. However, if a working LVM configuration already exists on your system, it is automatically activated upon entering the initial LVM configuration of a session. In this case, all disks containing a partition (belonging to an activated volume group) cannot be repartitioned. The Linux kernel cannot reread the modified partition table of a hard disk when any partition on this disk is in use. If you already have a working LVM configuration on your system, physical repartitioning should not be necessary. Instead, change the configuration of the logical volumes.

At the beginning of the physical volumes (PVs), information about the volume is written to the partition. To reuse such a partition for other non-LVM purposes, it is advisable to delete the beginning of this volume. For example, in the VG system and PV /dev/sda2, do this with the command dd if=/dev/zero of=/dev/sda2 bs=512 count=1.

Warning
Warning: File System for Booting

The file system used for booting (the root file system or /boot) must not be stored on an LVM logical volume. Instead, store it on a normal physical partition.

To change your /usr or swap, refer to Procedure 10.1, “Updating Init RAM Disk When Switching to Logical Volumes”.

For more details about LVM, see Storage Administration Guide.

12.2 LVM Configuration

  • Filename: lvm.xml
  • ID: sec.yast2.system.lvm

This section explains specific steps to take when configuring LVM. If you need information about the Logical Volume Manager in general, refer to the Section 5.1, “Understanding the Logical Volume Manager”.

Warning
Warning: Back up Your Data

Using LVM is sometimes associated with increased risk such as data loss. Risks also include application crashes, power failures, and faulty commands. Save your data before implementing LVM or reconfiguring volumes. Never work without a backup.

12.2.1 LVM Configuration with YaST

The YaST LVM configuration can be reached from the YaST Expert Partitioner (see Section 12.1, “Using the YaST Partitioner”) within the Volume Management item in the System View pane. The Expert Partitioner allows you to edit and delete existing partitions and create new ones that need to be used with LVM. The first task is to create PVs that provide space to a volume group:

  1. Select a hard disk from Hard Disks.

  2. Change to the Partitions tab.

  3. Click Add and enter the desired size of the PV on this disk.

  4. Use Do not format partition and change the File System ID to 0x8E Linux LVM. Do not mount this partition.

  5. Repeat this procedure until you have defined all the desired physical volumes on the available disks.

12.2.1.1 Creating Volume Groups

If no volume group exists on your system, you must add one (see Figure 12.3, “Creating a Volume Group”). It is possible to create additional groups by clicking Volume Management in the System View pane, and then on Add Volume Group. One single volume group is usually sufficient.

  1. Enter a name for the VG, for example, system.

  2. Select the desired Physical Extend Size. This value defines the size of a physical block in the volume group. All the disk space in a volume group is handled in blocks of this size.

  3. Add the prepared PVs to the VG by selecting the device and clicking Add. Selecting several devices is possible by holding Ctrl while selecting the devices.

  4. Select Finish to make the VG available to further configuration steps.

Creating a Volume Group
Figure 12.3: Creating a Volume Group

If you have multiple volume groups defined and want to add or remove PVs, select the volume group in the Volume Management list and click Resize. In the following window, you can add or remove PVs to the selected volume group.

12.2.1.2 Configuring Logical Volumes

After the volume group has been filled with PVs, define the LVs which the operating system should use in the next dialog. Choose the current volume group and change to the Logical Volumes tab. Add, Edit, Resize, and Delete LVs as needed until all space in the volume group has been occupied. Assign at least one LV to each volume group.

Logical Volume Management
Figure 12.4: Logical Volume Management

Click Add and go through the wizard-like pop-up that opens:

  1. Enter the name of the LV. For a partition that should be mounted to /home, a name like HOME could be used.

  2. Select the type of the LV. It can be either Normal Volume, Thin Pool, or Thin Volume. Note that you need to create a thin pool first, which can store individual thin volumes. The big advantage of thin provisioning is that the total sum of all thin volumes stored in a thin pool can exceed the size of the pool itself.

  3. Select the size and the number of stripes of the LV. If you have only one PV, selecting more than one stripe is not useful.

  4. Choose the file system to use on the LV and the mount point.

By using stripes it is possible to distribute the data stream in the LV among several PVs (striping). However, striping a volume can only be done over different PVs, each providing at least the amount of space of the volume. The maximum number of stripes equals to the number of PVs, where Stripe "1" means "no striping". Striping only makes sense with PVs on different hard disks, otherwise performance will decrease.

Warning
Warning: Striping

YaST cannot, at this point, verify the correctness of your entries concerning striping. Any mistake made here is apparent only later when the LVM is implemented on disk.

If you have already configured LVM on your system, the existing logical volumes can also be used. Before continuing, assign appropriate mount points to these LVs. With Finish, return to the YaST Expert Partitioner and finish your work there.

12.3 Soft RAID Configuration with YaST

  • Filename: raid.xml
  • ID: sec.yast2.system.raid

This section describes actions required to create and configure various types of RAID. In case you need background information about RAID, refer to Section 7.1, “Understanding RAID Levels”.

12.3.1 Soft RAID Configuration with YaST

The YaST RAID configuration can be reached from the YaST Expert Partitioner, described in Section 12.1, “Using the YaST Partitioner”. This partitioning tool enables you to edit and delete existing partitions and create new ones to be used with soft RAID:

  1. Select a hard disk from Hard Disks.

  2. Change to the Partitions tab.

  3. Click Add and enter the desired size of the raid partition on this disk.

  4. Use Do not Format the Partition and change the File System ID to 0xFD Linux RAID. Do not mount this partition.

  5. Repeat this procedure until you have defined all the desired physical volumes on the available disks.

For RAID 0 and RAID 1, at least two partitions are needed—for RAID 1, usually exactly two and no more. If RAID 5 is used, at least three partitions are required, RAID 6 and RAID 10 require at least four partitions. It is recommended to use partitions of the same size only. The RAID partitions should be located on different hard disks to decrease the risk of losing data if one is defective (RAID 1 and 5) and to optimize the performance of RAID 0. After creating all the partitions to use with RAID, click RAID › Add RAID to start the RAID configuration.

In the next dialog, choose between RAID levels 0, 1, 5, 6 and 10. Then, select all partitions with either the Linux RAID or Linux native type that should be used by the RAID system. No swap or DOS partitions are shown.

Tip
Tip: Classify Disks

For RAID types where the order of added disks matters, you can mark individual disks with one of the letters A to E. Click the Classify button, select the disk and click of the Class X buttons, where X is the letter you want to assign to the disk. Assign all available RAID disks this way, and confirm with OK. You can easily sort the classified disks with the Sorted or Interleaved buttons, or add a sort pattern from a text file with Pattern File.

RAID Partitions
Figure 12.5: RAID Partitions

To add a previously unassigned partition to the selected RAID volume, first click the partition then Add. Assign all partitions reserved for RAID. Otherwise, the space on the partition remains unused. After assigning all partitions, click Next to select the available RAID Options.

In this last step, set the file system to use, encryption and the mount point for the RAID volume. After completing the configuration with Finish, see the /dev/md0 device and others indicated with RAID in the expert partitioner.

12.3.2 Troubleshooting

Check the file /proc/mdstat to find out whether a RAID partition has been damaged. If Th system fails, shut down your Linux system and replace the defective hard disk with a new one partitioned the same way. Then restart your system and enter the command mdadm /dev/mdX --add /dev/sdX. Replace 'X' with your particular device identifiers. This integrates the hard disk automatically into the RAID system and fully reconstructs it.

Note that although you can access all data during the rebuild, you may encounter some performance issues until the RAID has been fully rebuilt.

12.3.3 For More Information

Configuration instructions and more details for soft RAID can be found in the HOWTOs at:

Linux RAID mailing lists are available, such as http://marc.info/?l=linux-raid.

13 Installing or Removing Software

  • Filename: yast2_sw.xml
  • ID: cha.y2.sw
Abstract

Use YaST's software management module to search for software components you want to add or remove. YaST resolves all dependencies for you. To install packages not shipped with the installation media, add additional software repositories to your setup and let YaST manage them. Keep your system up-to-date by managing software updates with the update applet.

Change the software collection of your system with the YaST Software Manager. This YaST module is available in two flavors: a graphical variant for X Window and a text-based variant to be used on the command line. The graphical flavor is described here—for details on the text-based YaST, see Chapter 5, YaST in Text Mode.

Note
Note: Confirmation and Review of Changes

When installing, updating or removing packages, any changes in the Software Manager are first applied after clicking Accept or Apply. YaST maintains a list with all actions, allowing you to review and modify your changes before applying them to the system.

13.1 Definition of Terms

Repository

A local or remote directory containing packages, plus additional information about these packages (package metadata).

(Repository) Alias/Repository Name

A short name for a repository (called Alias within Zypper and Repository Name within YaST). It can be chosen by the user when adding a repository and must be unique.

Repository Description Files

Each repository provides files describing content of the repository (package names, versions, etc.). These repository description files are downloaded to a local cache that is used by YaST.

Product

Represents a whole product, for example SUSE® Linux Enterprise Server.

Pattern

A pattern is an installable group of packages dedicated to a certain purpose. For example, the Laptop pattern contains all packages that are needed in a mobile computing environment. Patterns define package dependencies (such as required or recommended packages) and come with a preselection of packages marked for installation. This ensures that the most important packages needed for a certain purpose are available on your system after installation of the pattern. If necessary, you can manually select or deselect packages within a pattern.

Package

A package is a compressed file in rpm format that contains the files for a particular program.

Patch

A patch consists of one or more packages and may be applied by means of delta RPMs. It may also introduce dependencies to packages that are not installed yet.

Resolvable

A generic term for product, pattern, package or patch. The most commonly used type of resolvable is a package or a patch.

Delta RPM

A delta RPM consists only of the binary diff between two defined versions of a package, and therefore has the smallest download size. Before being installed, the full RPM package is rebuilt on the local machine.

Package Dependencies

Certain packages are dependent on other packages, such as shared libraries. In other terms, a package may require other packages—if the required packages are not available, the package cannot be installed. In addition to dependencies (package requirements) that must be fulfilled, some packages recommend other packages. These recommended packages are only installed if they are actually available, otherwise they are ignored and the package recommending them is installed nevertheless.

13.2 Registering Installed System

If you have skipped the registration during the installation or want to re-register your system, you can register the system at any time using the YaST module Product Registration or the command line tool SUSEConnect.

13.2.1 Registering with YaST

To register the system start YaST and to to Software, then Product Registration.

By default the system is registered with the SUSE Customer Center. If your organization provides local registration servers, you can either choose one form the list of auto-detected servers or provide the URL manually.

13.2.2 Registering with SUSEConnect

To register from the command line, use the command

tux > sudo SUSEConnect -r REGISTRATION_CODE -e EMAIL_ADDRESS

Replace REGISTRATION_CODE with the registration code you received with your copy of SUSE Linux Enterprise Server. Replace EMAIL_ADDRESS with the E-mail address associated with the SUSE account you or your organization uses to manage subscriptions.

To register with a local registration server, also provide the URL to the server:

tux > sudo SUSEConnect -r REGISTRATION_CODE -e EMAIL_ADDRESS --url "URL"

13.3 Using the YaST Software Manager

Start the software manager from the YaST Control Center by choosing Software › Software Management.

13.3.1 Views for Searching Packages or Patterns

The YaST software manager can install packages or patterns from all currently enabled repositories. It offers different views and filters to make it easier to find the software you are searching for. The Search view is the default view of the window. To change view, click View and select one of the following entries from the drop-down box. The selected view opens in a new tab.

Patterns

Lists all patterns available for installation on your system.

Package Groups

Lists all packages sorted by groups such as Graphics, Programming, or Security.

RPM Groups

Lists all packages sorted by functionality with groups and subgroups. For example Networking › Email › Clients.

Languages

A filter to list all packages needed to add a new system language.

Repositories

A filter to list packages by repository. To select more than one repository, hold the Ctrl key while clicking repository names. The pseudo repository @System lists all packages currently installed.

Search

Lets you search for a package according to certain criteria. Enter a search term and press Enter. Refine your search by specifying where to Search In and by changing the Search Mode. For example, if you do not know the package name but only the name of the application that you are searching for, try including the package Description in the search process.

Installation Summary

If you have already selected packages for installation, update or removal, this view shows the changes that will be applied to your system when you click Accept. To filter for packages with a certain status in this view, activate or deactivate the respective check boxes. Press ShiftF1 for details on the status flags.

Tip
Tip: Finding Packages Not Belonging to an Active Repository

To list all packages that do not belong to an active repository, choose View › Repositories › @System and then choose Secondary Filter › Unmaintained Packages. This is useful, for example, if you have deleted a repository and want to make sure no packages from that repository remain installed.

13.3.2 Installing and Removing Packages or Patterns

Certain packages are dependent on other packages, such as shared libraries. On the other hand, some packages cannot coexist with others on the system. If possible, YaST automatically resolves these dependencies or conflicts. If your choice results in a dependency conflict that cannot be automatically solved, you need to solve it manually as described in Section 13.3.4, “Checking Software Dependencies”.

Note
Note: Removal of Packages

When removing any packages, by default YaST only removes the selected packages. If you want YaST to also remove any other packages that become unneeded after removal of the specified package, select Options › Cleanup when deleting packages from the main menu.

  1. Search for packages as described in Section 13.3.1, “Views for Searching Packages or Patterns”.

  2. The packages found are listed in the right pane. To install a package or remove it, right-click it and choose Install or Delete. If the relevant option is not available, check the package status indicated by the symbol in front of the package name—press ShiftF1 for help.

    Tip
    Tip: Applying an Action to All Packages Listed

    To apply an action to all packages listed in the right pane, go to the main menu and choose an action from Package › All in This List.

  3. To install a pattern, right-click the pattern name and choose Install.

  4. It is not possible to remove a pattern per se. Instead, select the packages of a pattern you want to remove and mark them for removal.

  5. To select more packages, repeat the steps mentioned above.

  6. Before applying your changes, you can review or modify them by clicking View › Installation Summary. By default, all packages that will change status, are listed.

  7. To revert the status for a package, right-click the package and select one of the following entries: Keep if the package was scheduled to be deleted or updated, or Do Not Install if it was scheduled for installation. To abandon all changes and quit the Software Manager, click Cancel and Abandon.

  8. When you are finished, click Accept to apply your changes.

  9. In case YaST found dependencies on other packages, a list of packages that have additionally been chosen for installation, update or removal is presented. Click Continue to accept them.

    After all selected packages are installed, updated or removed, the YaST Software Manager automatically terminates.

Note
Note: Installing Source Packages

Installing source packages with YaST Software Manager is not possible at the moment. Use the command line tool zypper for this purpose. For more information, see Section 6.1.2.5, “Installing or Downloading Source Packages”.

13.3.3 Updating Packages

Instead of updating individual packages, you can also update all installed packages or all packages from a certain repository. When mass updating packages, the following aspects are generally considered:

  • priorities of the repositories that provide the package,

  • architecture of the package (for example, AMD64/Intel 64),

  • version number of the package,

  • package vendor.

Which of the aspects has the highest importance for choosing the update candidates depends on the respective update option you choose.

  1. To update all installed packages to the latest version, choose Package › All Packages › Update if Newer Version Available from the main menu.

    All repositories are checked for possible update candidates, using the following policy: YaST first tries to restrict the search to packages with the same architecture and vendor like the installed one. If the search is positive, the best update candidate from those is selected according to the process below. However, if no comparable package of the same vendor can be found, the search is expanded to all packages with the same architecture. If still no comparable package can be found, all packages are considered and the best update candidate is selected according to the following criteria:

    1. Repository priority: Prefer the package from the repository with the highest priority.

    2. If more than one package results from this selection, choose the one with the best architecture (best choice: matching the architecture of the installed one).

    If the resulting package has a higher version number than the installed one, the installed package will be updated and replaced with the selected update candidate.

    This option tries to avoid changes in architecture and vendor for the installed packages, but under certain circumstances, they are tolerated.

    Note
    Note: Update Unconditionally

    If you choose Package › All Packages › Update Unconditionally instead, the same criteria apply but any candidate package found is installed unconditionally. Thus, choosing this option might actually lead to downgrading some packages.

  2. To make sure that the packages for a mass update derive from a certain repository:

    1. Choose the repository from which to update as described in Section 13.3.1, “Views for Searching Packages or Patterns” .

    2. On the right hand side of the window, click Switch system packages to the versions in this repository. This explicitly allows YaST to change the package vendor when replacing the packages.

      When you proceed with Accept, all installed packages will be replaced by packages deriving from this repository, if available. This may lead to changes in vendor and architecture and even to downgrading some packages.

    3. To refrain from this, click Cancel switching system packages to the versions in this repository. Note that you can only cancel this until you click the Accept button.

  3. Before applying your changes, you can review or modify them by clicking View › Installation Summary. By default, all packages that will change status, are listed.

  4. If all options are set according to your wishes, confirm your changes with Accept to start the mass update.

13.3.4 Checking Software Dependencies

Most packages are dependent on other packages. If a package, for example, uses a shared library, it is dependent on the package providing this library. On the other hand, some packages cannot coexist, causing a conflict (for example, you can only install one mail transfer agent: sendmail or postfix). When installing or removing software, the Software Manager makes sure no dependencies or conflicts remain unsolved to ensure system integrity.

In case there exists only one solution to resolve a dependency or a conflict, it is resolved automatically. Multiple solutions always cause a conflict which needs to be resolved manually. If solving a conflict involves a vendor or architecture change, it also needs to be solved manually. When clicking Accept to apply any changes in the Software Manager, you get an overview of all actions triggered by the automatic resolver which you need to confirm.

By default, dependencies are automatically checked. A check is performed every time you change a package status (for example, by marking a package for installation or removal). This is generally useful, but can become exhausting when manually resolving a dependency conflict. To disable this function, go to the main menu and deactivate Dependencies › Autocheck. Manually perform a dependency check with Dependencies › Check Now. A consistency check is always performed when you confirm your selection with Accept.

To review a package's dependencies, right-click it and choose Show Solver Information. A map showing the dependencies opens. Packages that are already installed are displayed in a green frame.

Note
Note: Manually Solving Package Conflicts

Unless you are very experienced, follow the suggestions YaST makes when handling package conflicts, otherwise you may not be able to resolve them. Keep in mind that every change you make, potentially triggers other conflicts, so you can easily end up with a steadily increasing number of conflicts. In case this happens, Cancel the Software Manager, Abandon all your changes and start again.

Conflict Management of the Software Manager
Figure 13.1: Conflict Management of the Software Manager

13.3.4.1 Handling of Package Recommendations

In addition to the hard dependencies required to run a program (for example a certain library), a package can also have weak dependencies, that add for example extra functionality or translations. These weak dependencies are called package recommendations.

The way package recommendations are handled has slightly changed starting with SUSE Linux Enterprise Server 12 SP1. Nothing has changed when installing a new package—recommended packages are still installed by default.

Prior to SUSE Linux Enterprise Server 12 SP1, missing recommendations for already installed packages were installed automatically. Now these packages will no longer be installed automatically. To switch to the old default, set PKGMGR_REEVALUATE_RECOMMENDED="yes" in /etc/sysconfig/yast2. To install all missing recommendations for already installed packages, start YaST › Software Manager and choose Extras › Install All Matching Recommended Packages.

To disable the installation of recommended packages when installing new packages, deactivate Dependencies › Install Recommended Packages in the YaST Software Manager. If using the command line tool Zypper to install packages, use the option --no-recommends.

13.4 Managing Software Repositories and Services

  • Filename: yast2_sw_repo.xml
  • ID: sec.y2.sw.instsource

To install third-party software, add additional software repositories to your system. By default, the product repositories such as SUSE Linux Enterprise Server-DVD 12 SP3 and a matching update repository are automatically configured after you have registered your system. For more information about registration, see Section 6.8, “SUSE Customer Center Registration” or Section 20.9, “Registering Your System”. Depending on the initially selected product, an additional repository containing translations, dictionaries, etc. might also be configured.

To manage repositories, start YaST and select Software › Software Repositories. The Configured Software Repositories dialog opens. Here, you can also manage subscriptions to so-called Services by changing the View at the right corner of the dialog to All Services. A Service in this context is a Repository Index Service (RIS) that can offer one or more software repositories. Such a Service can be changed dynamically by its administrator or vendor.

Each repository provides files describing content of the repository (package names, versions, etc.). These repository description files are downloaded to a local cache that is used by YaST. To ensure their integrity, software repositories can be signed with the GPG Key of the repository maintainer. Whenever you add a new repository, YaST offers the ability to import its key.

Warning
Warning: Trusting External Software Sources

Before adding external software repositories to your list of repositories, make sure this repository can be trusted. SUSE is not responsible for any problems arising from software installed from third-party software repositories.

13.4.1 Adding Software Repositories

You can either add repositories from DVD/CD, removable mass storage devices (such as flash disks), a local directory, an ISO image or a network source.

To add repositories from the Configured Software Repositories dialog in YaST proceed as follows:

  1. Click Add.

  2. Select one of the options listed in the dialog:

    Adding a Software Repository
    Figure 13.2: Adding a Software Repository
    • To scan your network for installation servers announcing their services via SLP, select Scan Using SLP and click Next.

    • To add a repository from a removable medium, choose the relevant option and insert the medium or connect the USB device to the machine, respectively. Click Next to start the installation.

    • For the majority of repositories, you will be asked to specify the path (or URL) to the media after selecting the respective option and clicking Next. Specifying a Repository Name is optional. If none is specified, YaST will use the product name or the URL as repository name.

    The option Download Repository Description Files is activated by default. If you deactivate the option, YaST will automatically download the files later, if needed.

  3. Depending on the repository you have added, you may be prompted to import the repository's GPG key or asked to agree to a license.

    After confirming these messages, YaST will download and parse the metadata. It will add the repository to the list of Configured Repositories.

  4. If needed, adjust the repository Properties as described in Section 13.4.2, “Managing Repository Properties”.

  5. Confirm your changes with OK to close the configuration dialog.

  6. After having successfully added the repository, the software manager starts and you can install packages from this repository. For details, refer to Chapter 13, Installing or Removing Software.

13.4.2 Managing Repository Properties

The Configured Software Repositories overview of the Software Repositories lets you change the following repository properties:

Status

The repository status can either be Enabled or Disabled. You can only install packages from repositories that are enabled. To turn a repository off temporarily, select it and deactivate Enable. You can also double-click a repository name to toggle its status. To remove a repository completely, click Delete.

Refresh

When refreshing a repository, its content description (package names, versions, etc.) is downloaded to a local cache that is used by YaST. It is sufficient to do this once for static repositories such as CDs or DVDs, whereas repositories whose content changes often should be refreshed frequently. The easiest way to keep a repository's cache up-to-date is to choose Automatically Refresh. To do a manual refresh click Refresh and select one of the options.

Keep Downloaded Packages

Packages from remote repositories are downloaded before being installed. By default, they are deleted upon a successful installation. Activating Keep Downloaded Packages prevents the deletion of downloaded packages. The download location is configured in /etc/zypp/zypp.conf, by default it is /var/cache/zypp/packages.

Priority

The Priority of a repository is a value between 1 and 200, with 1 being the highest priority and 200 the lowest priority. Any new repositories that are added with YaST get a priority of 99 by default. If you do not care about a priority value for a certain repository, you can also set the value to 0 to apply the default priority to that repository (99). If a package is available in more than one repository, then the repository with the highest priority takes precedence. This is useful if you want to avoid downloading packages unnecessarily from the Internet by giving a local repository (for example, a DVD) a higher priority.

Important
Important: Priority Compared to Version

The repository with the highest priority takes precedence in any case. Therefore, make sure that the update repository always has the highest priority, otherwise you might install an outdated version that will not be updated until the next online update.

Name and URL

To change a repository name or its URL, select it from the list with a single-click and then click Edit.

13.4.3 Managing Repository Keys

To ensure their integrity, software repositories can be signed with the GPG Key of the repository maintainer. Whenever you add a new repository, YaST offers to import its key. Verify it as you would do with any other GPG key and make sure it does not change. If you detect a key change, something might be wrong with the repository. Disable the repository as an installation source until you know the cause of the key change.

To manage all imported keys, click GPG Keys in the Configured Software Repositories dialog. Select an entry with the mouse to show the key properties at the bottom of the window. Add, Edit or Delete keys with a click on the respective buttons.

13.5 Keeping the System Up-to-date

  • Filename: updater_gnome.xml
  • ID: sec.updater

SUSE offers a continuous stream of software security patches for your product. They can be installed using the YaST Online Update module. It also offers advanced features to customize the patch installation.

The GNOME desktop also provides a tool for installing patches and for installing package updates of packages that are already installed. In contrast to a Patch, a package update is only related to one package and provides a newer version of a package. The GNOME tool lets you install both patches and package updates with a few clicks as described in Section 13.5.2, “Installing Patches and Package Updates”.

13.5.1 The GNOME Software Updater

Whenever new patches or package updates are available, GNOME shows a notification about this at the bottom of the desktop (or on the locked screen).

Update Notification on GNOME Lock Screen
Figure 13.3: Update Notification on GNOME Lock Screen

13.5.2 Installing Patches and Package Updates

Whenever new patches or package updates are available, GNOME shows a notification about this at the bottom of the desktop (or on the locked screen).

Update Notification on GNOME Desktop
Figure 13.4: Update Notification on GNOME Desktop
  1. To install the patches and updates, click Install updates in the notification message. This opens the GNOME update viewer. Alternatively, open the update viewer from Applications › System Tools › Software Update or press AltF2 and enter gpk-update-viewer.

  2. All Security Updates and Important Updates are preselected. It is strongly recommended to install these patches. Other Updates can be manually selected by activating the respective check boxes. Get detailed information on a patch or package update by clicking its title.

  3. Click Install Updates to start the installation. You will be prompted for the root password.

  4. Enter the root password in the authentication dialog and proceed.

GNOME Update Viewer
Figure 13.5: GNOME Update Viewer

13.5.3 Configuring the GNOME Software Updater

To configure notifications, select Applications › System Settings › Notification › Software Update and adjust the desired settings.

To configure how often to check for updates or to activate or deactivate repositories, select Applications › System Tools › Settings › Software Settings. The tabs of the configuration dialog let you modify the following settings:

Update Settings
Check for Updates

Choose how often a check for updates is performed: Hourly, Daily, Weekly, or Never.

Check for Major Upgrades

Choose how often a check for major upgrades is performed: Daily, Weekly, or Never.

Check for updates when using mobile broadband

This configuration option is only available on mobile computers. Turned off by default.

Check for updates on battery power

This configuration option is only available on mobile computers. Turned off by default.

Software Sources
Repositories

Lists the repositories that will be checked for available patches and package updates. You can enable or disable certain repositories.

Important
Important: Keep Update Repository Enabled

To make sure that you are notified about any patches that are security-relevant, keep the Updates repository for your product enabled.

More options are configurable using gconf-editor: apps › gnome-packagekit.

14 Installing Modules, Extensions, and Third Party Add-On Products

  • Filename: yast2_sw_addon.xml
  • ID: cha.add-ons
Abstract

Modules and extensions add parts or functionality to the system. Modules are fully supported parts of SUSE Linux Enterprise Server with a different life cycle and update timeline. They are a set of packages, have a clearly defined scope and are delivered via online channel only.

Extensions, such as the Workstation Extension or the High Availability Extension, add extra functionality to the system and require an own registration key that is liable for costs. Extensions are delivered via online channel or physical media. Registering at the SUSE Customer Center or a local registration server is a prerequisite for subscribing to the online channels. The Package Hub (Section 14.5, “SUSE Package Hub”) and SUSE Software Development Kit (Section 14.4, “SUSE Software Development Kit (SDK) 12 SP3) extensions are exceptions which do not require a registration key and are not covered by SUSE support agreements.

A list of modules and extensions for your product is available after having registered your system at SUSE Customer Center or a local registration server. If you skipped the registration step during the installation, you can register your system at any time using the SUSE Customer Center Configuration module in YaST. For details, refer to Section 20.9, “Registering Your System”.

Some add-on products are also provided by third parties, for example, binary-only drivers that are needed by certain hardware to function properly. If you have such hardware, refer to the release notes for more information about availability of binary drivers for your system. The release notes are available from http://www.suse.com/releasenotes/, from YaST or from /usr/share/doc/release-notes/ in your installed system.

14.1 List of Optional Modules

Besides the base server operating system, SUSE Linux Enterprise Server 12 provides optional modules included in the subscription. Each module has a different lifecycle. This approach offers faster integration with upstream updates. Following is a list of all optional modules together with brief descriptions:

Web ans Scripting Module

The Web ans Scripting Module delivers a comprehensive set of scripting languages, frameworks and related tools to help developers and system administrators accelerate the creation of stable, modern web applications. The module includes recent versions of dynamic languages, such as PHP and Python. If you intend to run a web server or hosts applications that have web portals or require server-side scripts, you the Web and Scripting Module is a must.

Legacy Module

The Legacy Module helps you migrate applications from older systems to SUSE Linux Enterprise Server 12. For organizations moving from UNIX to Linux, this module may be essential. Many older applications require packages that are no longer available with the latest SUSE Linux Enterprise Server version. This module provides those packages. It includes packages such as sendmail, syslog-ng, IBM Java6 and a number of libraries (for example, openssl-0.9.8).

Public Cloud Module

The Public Cloud Module is a collection of tools to create and manage public cloud images from the command line. When building your own images with KIWI or SUSE Studio, initialization code specific to the target cloud is included in that image.

The Public Cloud Module contains four patterns:

  • Amazon–Web–Services (aws–cli, cloud–init)

  • Microsoft–Azure (WALinuxAgent)

  • Google–Cloud–Platform (gcimagebundle, google–api–python–client, google–cloud–sdk, google–daemon, google–startup–scripts)

  • OpenStack (OpenStack–heat–cfntools, cloud–init)

Toolchain Module

This module offers software developers a current toolchain consisting of GNU Compiler Collection (GCC) and related packages as well as updated applications, improvements, new standards and additional hardware features. It allows software developers to take benefit of new features of the most recent GCC release and brings improvements in language support, like for most C++14 changes and more Fortran 2008 and 2015 support, as well as many new optimizations. For more details, see https://gcc.gnu.org/gcc-5/changes.html.

Advanced Systems Management Module

This module contains three components to support system administrators in automating tasks in the data center and cloud: the configuration management tools 'CFEngine' and 'puppet', and the new "machinery" infrastructure. Machinery is a systems management toolbox that allows you to inspect systems remotely, store their system descriptions, and create new system images to deploy in data centers and clouds.

For more information about the Machinery project, see http://machinery-project.org/

Containers Module

This Module contains several packages revolving around containers and related tools, including the open source project Docker and prepackaged images for SUSE Linux Enterprise Server 11 and SUSE Linux Enterprise Server 12.

HPC Module

The HPC module provides a selected set of tools and components used in High Performance Computing environments. To fulfill changing customer needs for leading edge HPC support on both hardware and software, this module provides software components frequently updated to the latest versions available. The selection of software components has been inspired by (but not limited to) what is provided by the OpenHPC community project at http://openhpc.community/.

14.2 Installing Modules and Extensions from Online Channels

The following procedure requires that you have registered your system with SUSE Customer Center, or a local registration server. When registering your system, you will see a list of extensions and modules immediately after having completed Step 4 of Section 20.9, “Registering Your System”. In that case, skip the next steps and proceed with Step 2.

Note
Note: Viewing Already Installed Add-Ons

To view already installed add-ons, start YaST and select Software › Add-Ons

Procedure 14.1: Installing Add-ons and Extensions from Online Channels with YaST
  1. Start YaST and select Software › Add System Extensions or Modules.

    YaST connects to the registration server and displays a list of Available Extensions and Modules.

    Note
    Note: Available Extensions and Modules

    The amount of available extensions and modules depends on the registration server. A local registration server may only offer update repositories and no additional extensions.

    Note
    Note: Module Life Cycles

    Life cycle end dates of modules are available at https://scc.suse.com/docs/lifecycle/sle/12/modules.

  2. Click an entry to see its description.

  3. Select one or multiple entries for installation by activating their check marks.

    Installation of System Extensions
    Figure 14.1: Installation of System Extensions
  4. Click Next to proceed.

  5. Depending on the repositories to be added for the extension or module, you may be prompted to import the repository's GPG key or asked to agree to a license.

    After confirming these messages, YaST will download and parse the metadata. The repositories for the selected extensions will be added to your system—no additional installation sources are required.

  6. If needed, adjust the repository Properties as described in Section 13.4.2, “Managing Repository Properties”.

Note
Note: For More Information

White paper SUSE Linux Enterprise Server 12 Modules.

14.3 Installing Extensions and Third Party Add-On Products from Media

When installing an extension or add-on product from media, you can select various types of product media, like DVD/CD, removable mass storage devices (such as flash disks), or a local directory or ISO image. The media can also be provided by a network server, for example, via HTTP, FTP, NFS, or Samba.

  1. Start YaST and select Software › Add-On Products. Alternatively, start the YaST Add-On Products module from the command line with sudo yast2 add-on.

    The dialog will show an overview of already installed add-on products, modules and extensions.

    List of Installed Add-on Products, Modules and Extensions
    Figure 14.2: List of Installed Add-on Products, Modules and Extensions
  2. Choose Add to install a new add-on product.

  3. In the Add-On Product dialog, select the option that matches the type of medium from which you want to install:

    Installation of an Add-on Product or an Extension
    Figure 14.3: Installation of an Add-on Product or an Extension
    • To scan your network for installation servers announcing their services via SLP, select Scan Using SLP and click Next.

    • To add a repository from a removable medium, choose the relevant option and insert the medium or connect the USB device to the machine, respectively. Click Next to start the installation.

    • For most media types, you will prompted to specify the path (or URL) to the media after selecting the respective option and clicking Next. Specifying a Repository Name is optional. If none is specified, YaST will use the product name or the URL as the repository name.

    The option Download Repository Description Files is activated by default. If you deactivate the option, YaST will automatically download the files later, if needed.

  4. Depending on the repository you have added, you may be prompted to import the repository's GPG key or asked to agree to a license.

    After confirming these messages, YaST will download and parse the metadata. It will add the repository to the list of Configured Repositories.

  5. If needed, adjust the repository Properties as described in Section 13.4.2, “Managing Repository Properties”.

  6. Confirm your changes with OK to close the configuration dialog.

  7. After having successfully added the repository for the add-on media, the software manager starts and you can install packages. For details, refer to Chapter 13, Installing or Removing Software.

14.4 SUSE Software Development Kit (SDK) 12 SP3

SUSE Software Development Kit 12 SP3 is an extension for SUSE Linux Enterprise 12 SP3. It is a complete tool kit for application development. In fact, to provide a comprehensive build system, SUSE Software Development Kit 12 SP3 includes all the open source tools that were used to build the SUSE Linux Enterprise Server product. It provides you as a developer, independent software vendor (ISV), or independent hardware vendor (IHV) with all the tools needed to port applications to all the platforms supported by SUSE Linux Enterprise Desktop and SUSE Linux Enterprise Server.

The SUSE Software Development Kit does not require a registration key and is not covered by SUSE support agreements.

SUSE Software Development Kit also contains integrated development environments (IDEs), debuggers, code editors, and other related tools. It supports most major programming languages, including C, C++, Java, and most scripting languages. For your convenience, SUSE Software Development Kit includes multiple Perl packages that are not included in SUSE Linux Enterprise.

The SDK extension is available via an online channel from the SUSE Customer Center. Alternatively, go to http://download.suse.com/, search for SUSE Linux Enterprise Software Development Kit and download it from there. Refer to Chapter 14, Installing Modules, Extensions, and Third Party Add-On Products for details.

14.5 SUSE Package Hub

In the list of Available Extensions and Modules you find the SUSE Package Hub. It is available without any additional fee. It provides a large set of additional community packages for SUSE Linux Enterprise that can easily be installed but are not supported by SUSE.

More information about SUSE Package Hub and how to contribute is available at https://packagehub.suse.com/

Important
Important: SUSE Package Hub is Not Supported

Be aware that packages provided in the SUSE Package Hub are not officially supported by SUSE. SUSE only provides support for enabling the Package Hub repository and help with installation or deployment of the RPM packages.

15 Installing Multiple Kernel Versions

  • Filename: tuning_multikernel.xml
  • ID: cha.tuning.multikernel
Abstract

SUSE Linux Enterprise Server supports the parallel installation of multiple kernel versions. When installing a second kernel, a boot entry and an initrd are automatically created, so no further manual configuration is needed. When rebooting the machine, the newly added kernel is available as an additional boot option.

Using this functionality, you can safely test kernel updates while being able to always fall back to the proven former kernel. To do this, do not use the update tools (such as the YaST Online Update or the updater applet), but instead follow the process described in this chapter.

Warning
Warning: Support Entitlement

Be aware that you lose your entire support entitlement for the machine when installing a self-compiled or a third-party kernel. Only kernels shipped with SUSE Linux Enterprise Server and kernels delivered via the official update channels for SUSE Linux Enterprise Server are supported.

Tip
Tip: Check Your Boot Loader Configuration Kernel

It is recommended to check your boot loader configuration after having installed another kernel to set the default boot entry of your choice. See Section 12.3, “Configuring the Boot Loader with YaST” for more information.

15.1 Enabling and Configuring Multiversion Support

Installing multiple versions of a software package (multiversion support) is enabled by default since SUSE Linux Enterprise Server 12. To verify this setting, proceed as follows:

  1. Open /etc/zypp/zypp.conf with the editor of your choice as root.

  2. Search for the string multiversion. If multiversion is enabled for all kernel packages capable of this feature, the following line appears uncommented:

    multiversion = provides:multiversion(kernel)
  3. To restrict multiversion support to certain kernel flavors, add the package names as a comma-separated list to the multiversion option in /etc/zypp/zypp.conf—for example

    multiversion = kernel-default,kernel-default-base,kernel-source
  4. Save your changes.

Warning
Warning: Kernel Module Packages (KMP)

Make sure that required vendor provided kernel modules (Kernel Module Packages) are also installed for the new updated kernel. The kernel update process will not warn about eventually missing kernel modules because package requirements are still fulfilled by the old kernel that is kept on the system.

15.1.1 Automatically Deleting Unused Kernels

When frequently testing new kernels with multiversion support enabled, the boot menu quickly becomes confusing. Since a /boot partition usually has limited space you also might run into trouble with /boot overflowing. While you can delete unused kernel versions manually with YaST or Zypper (as described below), you can also configure libzypp to automatically delete kernels no longer used. By default no kernels are deleted.

  1. Open /etc/zypp/zypp.conf with the editor of your choice as root.

  2. Search for the string multiversion.kernels and activate this option by uncommenting the line. This option takes a comma-separated list of the following values:

    3.12.24-7.1 keep the kernel with the specified version number

    latest keep the kernel with the highest version number

    latest-N keep the kernel with the Nth highest version number

    running keep the running kernel

    oldest keep the kernel with the lowest version number (the one that was originally shipped with SUSE Linux Enterprise Server)

    oldest+N keep the kernel with the Nth lowest version number

    Here are some examples

    multiversion.kernels = latest,running

    Keep the latest kernel and the one currently running. This is similar to not enabling the multiversion feature, except that the old kernel is removed after the next reboot and not immediately after the installation.

    multiversion.kernels = latest,latest-1,running

    Keep the last two kernels and the one currently running.

    multiversion.kernels = latest,running,3.12.25.rc7-test

    Keep the latest kernel, the one currently running, and 3.12.25.rc7-test.

    Tip
    Tip: Keep the Running Kernel

    Unless you are using a special setup, always keep the kernel marked running.

    If you do not keep the running kernel, it will be deleted when updating the kernel. In turn, this means that all of the running kernel's modules are also deleted and cannot be loaded anymore.

    If you decide not to keep the running kernel, always reboot immediately after a kernel upgrade to avoid issues with modules.

15.1.2 Use Case: Deleting an Old Kernel after Reboot Only

You want to make sure that an old kernel will only be deleted after the system has rebooted successfully with the new kernel.

Change the following line in /etc/zypp/zypp.conf:

multiversion.kernels = latest,running

The previous parameters tell the system to keep the latest kernel and the running one only if they differ.

15.1.3 Use Case: Keeping Older Kernels as Fallback

You want to keep one or more kernel versions to have one or more spare kernels.

This can be useful if you need kernels for testing. If something goes wrong (for example, your machine does not boot), you still can use one or more kernel versions which are known to be good.

Change the following line in /etc/zypp/zypp.conf:

multiversion.kernels = latest,latest-1,latest-2,running

When you reboot your system after the installation of a new kernel, the system will keep three kernels: the current kernel (configured as latest,running) and its two immediate predecessors (configured as latest-1 and latest-2).

15.1.4 Use Case: Keeping a Specific Kernel Version

You make regular system updates and install new kernel versions. However, you are also compiling your own kernel version and want to make sure that the system will keep them.

Change the following line in /etc/zypp/zypp.conf:

multiversion.kernels = latest,3.12.28-4.20,running

When you reboot your system after the installation of a new kernel, the system will keep two kernels: the new and running kernel (configured as latest,running) and your self-compiled kernel (configured as 3.12.28-4.20).

15.2 Installing/Removing Multiple Kernel Versions with YaST

  1. Start YaST and open the software manager via Software › Software Management.

  2. List all packages capable of providing multiple versions by choosing View › Package Groups › Multiversion Packages.

    The YaST Software Manager: Multiversion View
    Figure 15.1: The YaST Software Manager: Multiversion View
  3. Select a package and open its Version tab in the bottom pane on the left.

  4. To install a package, click the check box next to it. A green check mark indicates it is selected for installation.

    To remove an already installed package (marked with a white check mark), click the check box next to it until a red X indicates it is selected for removal.

  5. Click Accept to start the installation.

15.3 Installing/Removing Multiple Kernel Versions with Zypper

  1. Use the command zypper se -s 'kernel*' to display a list of all kernel packages available:

    S | Name           | Type       | Version         | Arch   | Repository
    --+----------------+------------+-----------------+--------+-------------------
    v | kernel-default | package    | 2.6.32.10-0.4.1 | x86_64 | Alternative Kernel
    i | kernel-default | package    | 2.6.32.9-0.5.1  | x86_64 | (System Packages)
      | kernel-default | srcpackage | 2.6.32.10-0.4.1 | noarch | Alternative Kernel
    i | kernel-default | package    | 2.6.32.9-0.5.1  | x86_64 | (System Packages)
    ...
  2. Specify the exact version when installing:

    zypper in kernel-default-2.6.32.10-0.4.1
  3. When uninstalling a kernel, use the commands zypper se -si 'kernel*' to list all kernels installed and zypper rm PACKAGENAME-VERSION to remove the package.

16 Managing Users with YaST

  • Filename: yast2_userman.xml
  • ID: cha.y2.userman

During installation, you could have created a local user for your system. With the YaST module User and Group Management you can add more users or edit existing ones. It also lets you configure your system to authenticate users with a network server.

16.1 User and Group Administration Dialog

To administer users or groups, start YaST and click Security and Users › User and Group Management. Alternatively, start the User and Group Administration dialog directly by running sudo yast2 users & from a command line.

YaST User and Group Administration
Figure 16.1: YaST User and Group Administration

Every user is assigned a system-wide user ID (UID). Apart from the users which can log in to your machine, there are also several system users for internal use only. Each user is assigned to one or more groups. Similar to system users, there are also system groups for internal use.

Depending on the set of users you choose to view and modify with, the dialog (local users, network users, system users), the main window shows several tabs. These allow you to execute the following tasks:

Managing User Accounts

From the Users tab create, modify, delete or temporarily disable user accounts as described in Section 16.2, “Managing User Accounts”. Learn about advanced options like enforcing password policies, using encrypted home directories, or managing disk quotas in Section 16.3, “Additional Options for User Accounts”.

Changing Default Settings

Local users accounts are created according to the settings defined on the Defaults for New Users tab. Learn how to change the default group assignment, or the default path and access permissions for home directories in Section 16.4, “Changing Default Settings for Local Users”.

Assigning Users to Groups

Learn how to change the group assignment for individual users in Section 16.5, “Assigning Users to Groups”.

Managing Groups

From the Groups tab, you can add, modify or delete existing groups. Refer to Section 16.6, “Managing Groups” for information on how to do this.

Changing the User Authentication Method

When your machine is connected to a network that provides user authentication methods like NIS or LDAP, you can choose between several authentication methods on the Authentication Settings tab. For more information, refer to Section 16.7, “Changing the User Authentication Method”.

For user and group management, the dialog provides similar functionality. You can easily switch between the user and group administration view by choosing the appropriate tab at the top of the dialog.

Filter options allow you to define the set of users or groups you want to modify: On the Users or Group tab, click Set Filter to view and edit users or groups according to certain categories, such as Local Users or LDAP Users, for example (if you are part of a network which uses LDAP). With Set Filter › Customize Filter you can also set up and use a custom filter.

Depending on the filter you choose, not all of the following options and functions will be available from the dialog.

16.2 Managing User Accounts

YaST offers to create, modify, delete or temporarily disable user accounts. Do not modify user accounts unless you are an experienced user or administrator.

Note
Note: Changing User IDs of Existing Users

File ownership is bound to the user ID, not to the user name. After a user ID change, the files in the user's home directory are automatically adjusted to reflect this change. However, after an ID change, the user no longer owns the files he created elsewhere in the file system unless the file ownership for those files are manually modified.

In the following, learn how to set up default user accounts. For further options, refer to Section 16.3, “Additional Options for User Accounts”.

Procedure 16.1: Adding or Modifying User Accounts
  1. Open the YaST User and Group Administration dialog and click the Users tab.

  2. With Set Filter define the set of users you want to manage. The dialog lists users in the system and the groups the users belong to.

  3. To modify options for an existing user, select an entry and click Edit.

    To create a new user account, click Add.

  4. Enter the appropriate user data on the first tab, such as Username (which is used for login) and Password. This data is sufficient to create a new user. If you click OK now, the system will automatically assign a user ID and set all other values according to the default.

  5. Activate Receive System Mail if you want any kind of system notifications to be delivered to this user's mailbox. This creates a mail alias for root and the user can read the system mail without having to first log in as root.

    The mails sent by system services are stored in the local mailbox /var/spool/mail/USERNAME, where USERNAME is the login name of the selected user. To read e-mails, you can use the mail command.

  6. To adjust further details such as the user ID or the path to the user's home directory, do so on the Details tab.

    If you need to relocate the home directory of an existing user, enter the path to the new home directory there and move the contents of the current home directory with Move to New Location. Otherwise, a new home directory is created without any of the existing data.

  7. To force users to regularly change their password or set other password options, switch to Password Settings and adjust the options. For more details, refer to Section 16.3.2, “Enforcing Password Policies”.

  8. If all options are set according to your wishes, click OK.

  9. Click OK to close the administration dialog and to save the changes. A newly added user can now log in to the system using the login name and password you created.

    Alternatively, to save all changes without exiting the User and Group Administration dialog, click Expert Options › Write Changes Now.

Tip
Tip: Matching User IDs

For a new (local) user on a laptop which also needs to integrate into a network environment where this user already has a user ID, it is useful to match the (local) user ID to the ID in the network. This ensures that the file ownership of the files the user creates offline is the same as if he had created them directly on the network.

Procedure 16.2: Disabling or Deleting User Accounts
  1. Open the YaST User and Group Administration dialog and click the Users tab.

  2. To temporarily disable a user account without deleting it, select the user from the list and click Edit. Activate Disable User Login. The user cannot log in to your machine until you enable the account again.

  3. To delete a user account, select the user from the list and click Delete. Choose if you also want to delete the user's home directory or if you want to retain the data.

16.3 Additional Options for User Accounts

In addition to the settings for a default user account, SUSE® Linux Enterprise Server offers further options, such as options to enforce password policies, use encrypted home directories or define disk quotas for users and groups.

16.3.1 Automatic Login and Passwordless Login

If you use the GNOME desktop environment you can configure Auto Login for a certain user and Passwordless Login for all users. Auto login causes a user to become automatically logged in to the desktop environment on boot. This functionality can only be activated for one user at a time. Login without password allows all users to log in to the system after they have entered their user name in the login manager.

Warning
Warning: Security Risk

Enabling Auto Login or Passwordless Login on a machine that can be accessed by more than one person is a security risk. Without the need to authenticate, any user can gain access to your system and your data. If your system contains confidential data, do not use this functionality.

to activate auto login or login without password, access these functions in the YaST User and Group Administration with Expert Options › Login Settings.

16.3.2 Enforcing Password Policies

On any system with multiple users, it is a good idea to enforce at least basic password security policies. Users should change their passwords regularly and use strong passwords that cannot easily be exploited. For local users, proceed as follows:

Procedure 16.3: Configuring Password Settings
  1. Open the YaST User and Group Administration dialog and select the Users tab.

  2. Select the user for which to change the password options and click Edit.

  3. Switch to the Password Settings tab. The user's last password change is displayed on the tab.

  4. To make the user change his password at next login, activate Force Password Change.

  5. To enforce password rotation, set a Maximum Number of Days for the Same Password and a Minimum Number of Days for the Same Password.

  6. To remind the user to change his password before it expires, set the number of Days before Password Expiration to Issue Warning.

  7. To restrict the period of time the user can log in after his password has expired, change the value in Days after Password Expires with Usable Login.

  8. You can also specify a certain expiration date for the complete account. Enter the Expiration Date in YYYY-MM-DD format. Note that this setting is not password-related but rather applies to the account itself.

  9. For more information about the options and about the default values, click Help.

  10. Apply your changes with OK.

16.3.3 Managing Encrypted Home Directories

To protect data in home directories against theft and hard disk removal, you can create encrypted home directories for users. These are encrypted with LUKS (Linux Unified Key Setup), which results in an image and an image key being generated for the user. The image key is protected with the user's login password. When the user logs in to the system, the encrypted home directory is mounted and the contents are made available to the user.

With YaST, you can create encrypted home directories for new or existing users. To encrypt or modify encrypted home directories of already existing users, you need to know the user's current login password. By default, all existing user data is copied to the new encrypted home directory, but it is not deleted from the unencrypted directory.

Warning
Warning: Security Restrictions

Encrypting a user's home directory does not provide strong security from other users. If strong security is required, the system should not be physically shared.

Find background information about encrypted home directories and which actions to take for stronger security in Section 11.2, “Using Encrypted Home Directories”.

Procedure 16.4: Creating Encrypted Home Directories
  1. Open the YaST User and Group Management dialog and click the Users tab.

  2. To encrypt the home directory of an existing user, select the user and click Edit.

    Otherwise, click Add to create a new user account and enter the appropriate user data on the first tab.

  3. In the Details tab, activate Use Encrypted Home Directory. With Directory Size in MB, specify the size of the encrypted image file to be created for this user.

  4. Apply your settings with OK.

  5. Enter the user's current login password to proceed if YaST prompts for it.

  6. Click OK to close the administration dialog and save the changes.

    Alternatively, to save all changes without exiting the User and Group Administration dialog, click Expert Options › Write Changes Now.

Procedure 16.5: Modifying or Disabling Encrypted Home Directories

Of course, you can also disable the encryption of a home directory or change the size of the image file at any time.

  1. Open the YaST User and Group Administration dialog in the Users view.

  2. Select a user from the list and click Edit.

  3. to disable the encryption, switch to the Details tab and disable Use Encrypted Home Directory.

    If you need to enlarge or reduce the size of the encrypted image file for this user, change the Directory Size in MB.

  4. Apply your settings with OK.

  5. Enter the user's current login password to proceed if YaST prompts for it.

  6. Click OK to close the administration dialog and save the changes.

    Alternatively, to save all changes without exiting the User and Group Administration dialog, click Expert Options › Write Changes Now.

16.3.4 Managing Quotas

To prevent system capacities from being exhausted without notification, system administrators can set up quotas for users or groups. Quotas can be defined for one or more file systems and restrict the amount of disk space that can be used and the number of inodes (index nodes) that can be created there. Inodes are data structures on a file system that store basic information about a regular file, directory, or other file system object. They store all attributes of a file system object (like user and group ownership, read, write, or execute permissions), except file name and contents.

SUSE Linux Enterprise Server allows usage of soft and hard quotas. Additionally, grace intervals can be defined that allow users or groups to temporarily violate their quotas by certain amounts.

Soft Quota

Defines a warning level at which users are informed that they are nearing their limit. Administrators will urge the users to clean up and reduce their data on the partition. The soft quota limit is usually lower than the hard quota limit.

Hard Quota

Defines the limit at which write requests are denied. When the hard quota is reached, no more data can be stored and applications may crash.

Grace Period

Defines the time between the overflow of the soft quota and a warning being issued. Usually set to a rather low value of one or several hours.

Procedure 16.6: Enabling Quota Support for a Partition

To configure quotas for certain users and groups, you need to enable quota support for the respective partition in the YaST Expert Partitioner first.

Note
Note: Quotas Btrfs Partitions

Quotas for Btrfs partitions are handled differently. For more information, see Section 1.2.5, “Btrfs Quota Support for Subvolumes”.

  1. In YaST, select System › Partitioner and click Yes to proceed.

  2. In the Expert Partitioner, select the partition for which to enable quotas and click Edit.

  3. Click Fstab Options and activate Enable Quota Support. If the quota package is not already installed, it will be installed once you confirm the respective message with Yes.

  4. Confirm your changes and leave the Expert Partitioner.

  5. Make sure the service quotaon is running by entering the following command:

    systemctl status quotaon

    It should be marked as being active. If this is not the case, start it with the command systemctl start quotaon.

Procedure 16.7: Setting Up Quotas for Users or Groups

Now you can define soft or hard quotas for specific users or groups and set time periods as grace intervals.

  1. In the YaST User and Group Administration, select the user or the group you want to set the quotas for and click Edit.

  2. On the Plug-Ins tab, select the Manage User Quota entry and click Launch to open the Quota Configuration dialog.

  3. From File System, select the partition to which the quota should apply.

  4. Below Size Limits, restrict the amount of disk space. Enter the number of 1 KB blocks the user or group may have on this partition. Specify a Soft Limit and a Hard Limit value.

  5. Additionally, you can restrict the number of inodes the user or group may have on the partition. Below Inodes Limits, enter a Soft Limit and Hard Limit.

  6. You can only define grace intervals if the user or group has already exceeded the soft limit specified for size or inodes. Otherwise, the time-related text boxes are not activated. Specify the time period for which the user or group is allowed to exceed the limits set above.

  7. Confirm your settings with OK.

  8. Click OK to close the administration dialog and save the changes.

    Alternatively, to save all changes without exiting the User and Group Administration dialog, click Expert Options › Write Changes Now.

SUSE Linux Enterprise Server also ships command-line tools like repquota or warnquota. System administrators can use this tools to control the disk usage or send e-mail notifications to users exceeding their quota. Using quota_nld, administrators can also forward kernel messages about exceeded quotas to D-BUS. For more information, refer to the repquota, the warnquota and the quota_nld man page.

16.4 Changing Default Settings for Local Users

When creating new local users, several default settings are used by YaST. These include, for example, the primary group and the secondary groups the user belongs to, or the access permissions of the user's home directory. You can change these default settings to meet your requirements:

  1. Open the YaST User and Group Administration dialog and select the Defaults for New Users tab.

  2. To change the primary group the new users should automatically belong to, select another group from Default Group.

  3. To modify the secondary groups for new users, add or change groups in Secondary Groups. The group names must be separated by commas.

  4. If you do not want to use /home/USERNAME as default path for new users' home directories, modify the Path Prefix for Home Directory.

  5. To change the default permission modes for newly created home directories, adjust the umask value in Umask for Home Directory. For more information about umask, refer to Chapter 10, Access Control Lists in Linux and to the umask man page.

  6. For information about the individual options, click Help.

  7. Apply your changes with OK.

16.5 Assigning Users to Groups

Local users are assigned to several groups according to the default settings which you can access from the User and Group Administration dialog on the Defaults for New Users tab. In the following, learn how to modify an individual user's group assignment. If you need to change the default group assignments for new users, refer to Section 16.4, “Changing Default Settings for Local Users”.

Procedure 16.8: Changing a User's Group Assignment
  1. Open the YaST User and Group Administration dialog and click the Users tab. It lists users and the groups the users belong to.

  2. Click Edit and switch to the Details tab.

  3. To change the primary group the user belongs to, click Default Group and select the group from the list.

  4. To assign the user additional secondary groups, activate the corresponding check boxes in the Additional Groups list.

  5. Click OK to apply your changes.

  6. Click OK to close the administration dialog and save the changes.

    Alternatively, to save all changes without exiting the User and Group Administration dialog, click Expert Options › Write Changes Now.

16.6 Managing Groups

With YaST you can also easily add, modify or delete groups.

Procedure 16.9: Creating and Modifying Groups
  1. Open the YaST User and Group Management dialog and click the Groups tab.

  2. With Set Filter define the set of groups you want to manage. The dialog lists groups in the system.

  3. To create a new group, click Add.

  4. To modify an existing group, select the group and click Edit.

  5. In the following dialog, enter or change the data. The list on the right shows an overview of all available users and system users which can be members of the group.

  6. To add existing users to a new group select them from the list of possible Group Members by checking the corresponding box. To remove them from the group deactivate the box.

  7. Click OK to apply your changes.

  8. Click OK to close the administration dialog and save the changes.

    Alternatively, to save all changes without exiting the User and Group Administration dialog, click Expert Options › Write Changes Now.

To delete a group, it must not contain any group members. To delete a group, select it from the list and click Delete. Click OK to close the administration dialog and save the changes. Alternatively, to save all changes without exiting the User and Group Administration dialog, click Expert Options › Write Changes Now.

16.7 Changing the User Authentication Method

When your machine is connected to a network, you can change the authentication method. The following options are available:

NIS

Users are administered centrally on a NIS server for all systems in the network. For details, see Chapter 3, Using NIS.

SSSD

The System Security Services Daemon (SSSD) can locally cache user data and then allow users to use the data, even if the real directory service is (temporarily) unreachable. For details, see Section 4.3, “SSSD”.

Samba

SMB authentication is often used in mixed Linux and Windows networks. For details, see Chapter 28, Samba.

To change the authentication method, proceed as follows:

  1. Open the User and Group Administration dialog in YaST.

  2. Click the Authentication Settings tab to show an overview of the available authentication methods and the current settings.

  3. To change the authentication method, click Configure and select the authentication method you want to modify. This takes you directly to the client configuration modules in YaST. For information about the configuration of the appropriate client, refer to the following sections:

    NIS:  Section 3.2, “Configuring NIS Clients”

    LDAP:  Section 4.2, “Configuring an Authentication Client with YaST”

    Samba:  Section 28.5.1, “Configuring a Samba Client with YaST”

  4. After accepting the configuration, return to the User and Group Administration overview.

  5. Click OK to close the administration dialog.

17 Changing Language and Country Settings with YaST

  • Filename: yast2_lang.xml
  • ID: cha.y2.lang

Working in different countries or having to work in a multilingual environment requires your computer to be set up to support this. SUSE® Linux Enterprise Server can handle different locales in parallel. A locale is a set of parameters that defines the language and country settings reflected in the user interface.

The main system language was selected during installation and keyboard and time zone settings were adjusted. However, you can install additional languages on your system and determine which of the installed languages should be the default.

For those tasks, use the YaST language module as described in Section 17.1, “Changing the System Language”. Install secondary languages to get optional localization if you need to start applications or desktops in languages other than the primary one.

Apart from that, the YaST timezone module allows you to adjust your country and timezone settings accordingly. It also lets you synchronize your system clock against a time server. For details, refer to Section 17.2, “Changing the Country and Time Settings”.

17.1 Changing the System Language

Depending on how you use your desktop and whether you want to switch the entire system to another language or only the desktop environment itself, there are several ways to do this:

Changing the System Language Globally

Proceed as described in Section 17.1.1, “Modifying System Languages with YaST” and Section 17.1.2, “Switching the Default System Language” to install additional localized packages with YaST and to set the default language. Changes are effective after the next login. To ensure that the entire system reflects the change, reboot the system or close and restart all running services, applications, and programs.

Changing the Language for the Desktop Only

Provided you have previously installed the desired language packages for your desktop environment with YaST as described below, you can switch the language of your desktop using the desktop's control center. After the X server has been restarted, your entire desktop reflects your new choice of language. Applications not belonging to your desktop framework are not affected by this change and may still appear in the language that was set in YaST.

Temporarily Switching Languages for One Application Only

You can also run a single application in another language (that has already been installed with YaST). To do so, start it from the command line by specifying the language code as described in Section 17.1.3, “Switching Languages for Standard X and GNOME Applications”.

17.1.1 Modifying System Languages with YaST

YaST knows two different language categories:

Primary Language

The primary language set in YaST applies to the entire system, including YaST and the desktop environment. This language is used whenever available unless you manually specify another language.

Secondary Languages

Install secondary languages to make your system multilingual. Languages installed as secondary languages can be selected manually for a specific situation. For example, use a secondary language to start an application in a certain language to do word processing in this language.

Before installing additional languages, determine which of them should be the default system language (primary language).

To access the YaST language module, start YaST and click System › Language. Alternatively, start the Languages dialog directly by running sudo yast2 language & from a command line.

Procedure 17.1: Installing Additional Languages

When installing additional languages, YaST also allows you to set different locale settings for the user root, see Step 4. The option Locale Settings for User root determines how the locale variables (LC_*) in the file /etc/sysconfig/language are set for root. You can either set them to the same locale as for normal users, keep it unaffected by any language changes or only set the variable RC_LC_CTYPE to the same values as for the normal users. This variable sets the localization for language-specific function calls.

  1. To add additional languages in the YaST language module, select the Secondary Languages you want to install.

  2. To make a language the default language, set it as Primary Language.

  3. Additionally, adapt the keyboard to the new primary language and adjust the time zone, if appropriate.

    Tip
    Tip: Advanced Settings

    For advanced keyboard or time zone settings, select Hardware › System Keyboard Layout or System › Date and Time in YaST to start the respective dialogs. For more information, refer to Section 11.1, “Setting Up Your System Keyboard Layout” and Section 17.2, “Changing the Country and Time Settings”.

  4. To change language settings specific to the user root, click Details.

    1. Set Locale Settings for User root to the desired value. For more information, click Help.

    2. Decide if you want to Use UTF-8 Encoding for root or not.

  5. If your locale was not included in the list of primary languages available, try specifying it with Detailed Locale Setting. However, some localization may be incomplete.

  6. Confirm your changes in the dialogs with OK. If you have selected secondary languages, YaST installs the localized software packages for the additional languages.

The system is now multilingual. However, to start an application in a language other than the primary one, you need to set the desired language explicitly as explained in Section 17.1.3, “Switching Languages for Standard X and GNOME Applications”.

17.1.2 Switching the Default System Language

  1. To globally switch the default system language, start the YaST language module.

  2. Select the desired new system language as Primary Language.

    Important
    Important: Deleting Former System Languages

    If you switch to a different primary language, the localized software packages for the former primary language will be removed from the system. To switch the default system language but keep the former primary language as additional language, add it as Secondary Language by enabling the respective check box.

  3. Adjust the keyboard and time zone options as desired.

  4. Confirm your changes with OK.

  5. After YaST has applied the changes, restart current X sessions (for example, by logging out and logging in again) to make YaST and the desktop applications reflect your new language settings.

17.1.3 Switching Languages for Standard X and GNOME Applications

After you have installed the respective language with YaST, you can run a single application in another language.

Start the application from the command line by using the following command:

LANG=LANGUAGE application

For example, to start f-spot in German, run LANG=de_DE f-spot. For other languages, use the appropriate language code. Get a list of all language codes available with the locale  -av command.

17.2 Changing the Country and Time Settings

Using the YaST date and time module, adjust your system date, clock and time zone information to the area you are working in. To access the YaST module, start YaST and click System › Date and Time. Alternatively, start the Clock and Time Zone dialog directly by running sudo yast2 timezone & from a command line.

First, select a general region, such as Europe. Choose an appropriate country that matches the one you are working in, for example, Germany.

Depending on which operating systems run on your workstation, adjust the hardware clock settings accordingly:

  • If you run another operating system on your machine, such as Microsoft Windows*, it is likely your system does not use UTC, but local time. In this case, deactivate Hardware Clock Set To UTC.

  • If you only run Linux on your machine, set the hardware clock to UTC and have the switch from standard time to daylight saving time performed automatically.

Important
Important: Set the Hardware Clock to UTC

The switch from standard time to daylight saving time (and vice versa) can only be performed automatically when the hardware clock (CMOS clock) is set to UTC. This also applies if you use automatic time synchronization with NTP, because automatic synchronization will only be performed if the time difference between the hardware and system clock is less than 15 minutes.

Since a wrong system time can cause serious problems (missed backups, dropped mail messages, mount failures on remote file systems, etc.) it is strongly recommended to always set the hardware clock to UTC.

You can change the date and time manually or opt for synchronizing your machine against an NTP server, either permanently or only for adjusting your hardware clock.

Procedure 17.2: Manually Adjusting Time and Date
  1. In the YaST timezone module, click Other Settings to set date and time.

  2. Select Manually and enter date and time values.

  3. Confirm your changes.

Procedure 17.3: Setting Date and Time With NTP Server
  1. Click Other Settings to set date and time.

  2. Select Synchronize with NTP Server.

  3. Enter the address of an NTP server, if not already populated.

  4. Click Synchronize Now to get your system time set correctly.

  5. To use NTP permanently, enable Save NTP Configuration.

  6. With the Configure button, you can open the advanced NTP configuration. For details, see Section 24.1, “Configuring an NTP Client with YaST”.

  7. Confirm your changes.

Part VI Updating and Upgrading SUSE Linux Enterprise

18 Life Cycle and Support

This chapter provides background information on terminology, SUSE product lifecycles and Service Pack releases, and recommended upgrade policies.

19 Upgrading SUSE Linux Enterprise

SUSE® Linux Enterprise (SLE) allows to upgrade an existing system to the new version, for example, going from SLE 11 SP4 to the latest SLE 12 service pack. No new installation is needed. Existing data, such as home and data directories and system configuration, is kept intact. You can update from a local CD or DVD drive or from a central network installation source.

This chapter explains how to manually upgrade your SUSE Linux Enterprise system, be it by DVD, network, an automated process, or SUSE Manager.

20 Upgrading Offline

This chapter describes how to upgrade an existing SUSE Linux Enterprise installation using YaST which is booted from an installation medium. The YaST installer can, for example, be started from a DVD, over the network, or from the hard disk the system resides on.

21 Upgrading Online

SUSE offers an intuitive graphical and a simple command line tool to upgrade a running system to a new service pack. They provide support for rollback of service packs and more. This chapter explains how to do a service pack upgrade step by step with these tools.

22 Backporting Source Code

SUSE extensively uses backports, for example for the migration of current software fixes and features into released SUSE Linux Enterprise packages. The information in this chapter explains why it can be misleading to compare version numbers to judge the capabilities and the security of SUSE Linux Enterprise software packages. This chapter also explains how SUSE keeps the system software secure and current while maintaining compatibility for your application software on top of SUSE Linux Enterprise products. You will also learn how to check which public security issues actually are addressed in your SUSE Linux Enterprise system software, and the current status of your software.

18 Life Cycle and Support

  • Filename: sle_update_background.xml
  • ID: cha.update.background
Abstract

This chapter provides background information on terminology, SUSE product lifecycles and Service Pack releases, and recommended upgrade policies.

18.1 Terminology

This section uses several terms. To understand the information, read the definitions below:

Backporting

Backporting is the act of adapting specific changes from a newer version of software and applying it to an older version. The most commonly used case is fixing security holes in older software components. Usually it is also part of a maintenance model to supply enhancements or (less commonly) new features.

Delta RPM

A delta RPM consists only of the binary diff between two defined versions of a package, and therefore has the smallest download size. Before being installed, the full RPM package is rebuilt on the local machine.

Downstream

A metaphor of how software is developed in the open source world (compare it with upstream). The term downstream refers to people or organizations like SUSE who integrate the source code from upstream with other software to build a distribution which is then used by end users. Thus, the software flows downstream from its developers via the integrators to the end users.

Extensions, Add-On Products

Extensions and third party add-on products provide additional functionality of product value to SUSE Linux Enterprise Server. They are provided by SUSE and by SUSE partners, and they are registered and installed on top of the base product SUSE Linux Enterprise Server.

LTSS

LTSS is the abbreviation for Long Term Service Pack Support, which is available as an extension for SUSE Linux Enterprise Server.

Major Release, General Availability (GA) Version

The major release of SUSE Linux Enterprise (or any software product) is a new version which brings new features and tools, decommissions previously deprecated components and comes with backward-incompatible changes. Major releases for example are SUSE Linux Enterprise 11 or 12.

Migration

Updating to a Service Pack (SP) by using the online update tools or an installation medium to install the respective patches. It updates all packages of the installed system to the latest state.

Migration Targets

Set of compatible products to which a system can be migrated, containing the version of the products/extensions and the URL of the repository. Migration targets can change over time and depend on installed extensions. Multiple migration targets can be selected, for example SLE 12 SP2 and SES2 or SLE 12 SP2 and SES3.

Modules

Modules are fully supported parts of SUSE Linux Enterprise Server with a different life cycle. They have a clearly defined scope and are delivered via online channel only. Registering at the SUSE Customer Center, SMT (Subscription Management Tool), or SUSE Manager is a prerequisite for being able to subscribe to these channels.

Package

A package is a compressed file in rpm format that contains all files for a particular program, including optional components like configuration, examples, and documentation.

Patch

A patch consists of one or more packages and may be applied by means of delta RPMs. It may also introduce dependencies to packages that are not installed yet.

Service Packs (SP)

Combines several patches into a form that is easy to install or deploy. Service packs are numbered and usually contain security fixes, updates, upgrades, or enhancements of programs.

Upstream

A metaphor of how software is developed in the open source world (compare it with downstream). The term upstream refers to the original project, author or maintainer of a software that is distributed as source code. Feedback, patches, feature enhancements, or other improvements flow from end users or contributors to upstream developers. They decide if the request will be integrated or rejected.

If the project members decide to integrate the request, it will show up in newer versions of the software. An accepted request will benefit all parties involved.

If a request is not accepted, it may be for different reasons. Either it is in a state that is not compliant with the project's guidelines, it is invalid, it is already integrated, or it is not in the interest or roadmap of the project. An unaccepted request makes it harder for upstream developers as they need to synchronize their patches with the upstream code. This practice is generally avoided, but sometimes it is still needed.

Update

Installation of a newer minor version of a package, which usually contains security or bug fixes.

Upgrade

Installation of a newer major version of a package or distribution, which brings new features.

18.2 Product Life Cycle

SUSE has the following life cycle for products:

  • SUSE Linux Enterprise Server has a 13-year life cycle: 10 years of general support and 3 years of extended support.

  • SUSE Linux Enterprise Desktop has a 10-year life cycle: 7 years of general support and 3 years of extended support.

  • Major releases are made every 4 years. Service packs are made every 12-14 months.

SUSE supports previous service packs for 6 months after the release of the new service pack. Figure 18.1, “Major Releases and Service Packs” depicts some mentioned aspects.

Major Releases and Service Packs
Figure 18.1: Major Releases and Service Packs

If you need additional time to design, validate and test your upgrade plans, Long Term Service Pack Support can extend the support you get by an additional 12 to 36 months in 12-month increments, giving you a total of between 2 and 5 years of support on any service pack (see Figure 18.2, “Long Term Service Pack Support”).

Long Term Service Pack Support
Figure 18.2: Long Term Service Pack Support

For more information refer to https://www.suse.com/products/long-term-service-pack-support/.

For the life cycles of all products refer to https://www.suse.com/lifecycle/.

18.3 Module Life Cycles

With SUSE Linux Enterprise 12, SUSE introduces modular packaging. The modules are distinct sets of packages grouped into their own maintenance channel and updated independently of service pack life cycles. This allows you to get timely and easy access to the latest technology in areas where innovation is occurring at a rapid pace. For information about the life cycles of modules refer to https://scc.suse.com/docs/lifecycle/sle/12/modules.

18.4 Generating Periodic Life Cycle Report

SUSE Linux Enterprise Server can regularly check for changes in the support status of all installed products and send the report via e-mail in case of changes. To generate the report, install the zypper-lifecycle-plugin with zypper in zypper-lifecycle-plugin.

Enable the report generation on your system with systemctl:

root # systemctl enable lifecycle-report

The recipient and subject of the report e-mail, as well as the report generation period can be configured in the file /etc/sysconfig/lifecycle-report with any text editor. The settings MAIL_TO and MAIL_SUBJ define the mail recipient and subject, while DAYS sets the interval at which the report is generated.

The report displays changes in the support status after the change occurred and not in advance. If the change occurs right after the generation of the last report, it can take up to 14 days until you are notified of the change. Take this into account when setting the DAYS option. Change the following configuration entries to fit your requirements:

MAIL_TO='root@localhost'
MAIL_SUBJ='Lifecycle report'
DAYS=14

The latest report is available in the file /var/lib/lifecycle/report. The file contains two sections. The first section informs about the end of support for used products. The second section lists packages with their support end dates and update availability.

18.5 Support Levels

The range for extended support levels starts from year 10 and ends in year 13. These contain continued L3 engineering level diagnosis and reactive critical bug fixes. With these support levels, you will receive updates for trivially exploitable root exploits in the kernel and other root exploits directly executable without user interaction. Furthermore, they support existing workloads, software stacks, and hardware with limited package exclusion list. Find an overview in Table 18.1, “Security Updates and Bug Fixes”.

Table 18.1: Security Updates and Bug Fixes
 

General Support for Most Recent Service Pack (SP)

General Support for Previous SP, with LTSS

Extended Support with LTSS

Feature

Year 1-5

Year 6-7

Year 8-10

Year 4-10

Year 10-13

Technical Services

Yes

Yes

Yes

Yes

Yes

Access to Patches and Fixes

Yes

Yes

Yes

Yes

Yes

Access to Documentation and Knowledge Base

Yes

Yes

Yes

Yes

Yes

Support for Existing Stacks and Workloads

Yes

Yes

Yes

Yes

Yes

Support for New Deployments

Yes

Yes

Limited (Based on partner and customer requests)

Limited (Based on partner and customer requests)

No

Enhancement Requests

Yes

Limited (Based on partner and customer requests)

Limited (Based on partner and customer requests)

No

No

Hardware Enablement and Optimization

Yes

Limited (Based on partner and customer requests)

Limited (Based on partner and customer requests)

No

No

Driver updates via SUSE SolidDriver Program (formerly PLDP)

Yes

Yes

Limited (Based on partner and customer requests)

Limited (Based on partner and customer requests)

No

Backport of Fixes from Recent SP

Yes

Yes

Limited (Based on partner and customer requests)

N/A

N/A

Critical Security Updates

Yes

Yes

Yes

Yes

Yes

Defect Resolution

Yes

Yes

Limited (Severity Level 1 and 2 defects only)

Limited (Severity Level 1 and 2 defects only)

Limited (Severity Level 1 and 2 defects only)

18.6 Repository Model

The repository layout corresponds to the product lifecycles. The following sections contain a list of all relevant repositories.

Description of Required Repositories
Updates

Maintenance updates to packages in the corresponding Core or Pool repository.

Pool

Containing all binary RPMs from the installation media, plus pattern information and support status metadata.

Description of Optional Repositories
Debuginfo-Pool, Debuginfo-Updates

These repositories contain static content. Of these two, only the Debuginfo-Updates repository receives updates. Enable these repositories if you need to install libraries with debug information in case of an issue.

18.6.1 Required Repositories for SUSE Linux Enterprise Server

SLES 11 SP3
SLES11-SP3-Pool
SLES11-SP3-Updates
SLES 11 SP4
SLES11-SP4-Pool
SLES11-SP4-Updates
SLES 12
SLES12-GA-Pool
SLES12-GA-Updates
SLES 12 SP1
SLES12-SP1-Pool
SLES12-SP1-Updates
SLES 12 SP2
SLES12-SP2-Pool
SLES12-SP2-Updates
SLES 12 SP3
SLES12-SP3-Pool
SLES12-SP3-Updates

18.6.2 Optional Repositories for SUSE Linux Enterprise Server

SLES 11 SP3
SLES11-SP3-Debuginfo-Core
SLES11-SP3-Debuginfo-Updates
SLES11-SP3-Extension-Store
SLES11-SP3-Extra
SLES 12
SLES12-GA-Debuginfo-Core
SLES12-GA-Debuginfo-Updates
SLES 12 SP1
SLES12-SP1-Debuginfo-Core
SLES12-SP1-Debuginfo-Updates
SLES 12 SP2
SLES12-SP2-Debuginfo-Core
SLES12-SP2-Debuginfo-Updates
SLES 12 SP3
SLES12-SP3-Debuginfo-Core
SLES12-SP3-Debuginfo-Updates

18.6.3 Module-Specific Repositories for SUSE Linux Enterprise Server

The following listing contains only the core repositories for each module, but not Debuginfo or Source repositories.

Modules Available for SLES 12 GA/SP1/SP2/SP3
  • Advanced Systems Management Module: CFEngine, Puppet and the Machinery tool

    SLE-Module-Adv-Systems-Management12-Pool
    SLE-Module-Adv-Systems-Management12-Updates
  • Containers Module: Docker, tools, prepackaged images

    SLE-Module-Containers12-Pool
    SLE-Module-Containers12-Updates
  • Legacy Module: Sendmail, old IMAP stack, old Java, … (not available on AArch64)

    SLE-Module-Legacy12-Pool
    SLE-Module-Legacy12-Updates
  • Public Cloud Module: public cloud initialization code and tools

    SLE-Module-Public-Cloud12-Pool
    SLE-Module-Public-Cloud12-Updates
  • Toolchain Module: GNU Compiler Collection (GCC)

    SLE-Module-Toolchain12-Pool
    SLE-Module-Toolchain12-Updates
  • Web and Scripting Module: PHP, Python, Ruby on Rails

    SLE-Module-Web-Scripting12-Pool
    SLE-Module-Web-Scripting12-Updates
Modules Available for SLES 12 GA/SP1
  • Certifications Module: FIPS 140-2 certification-specific packages (not available on AArch64 and POWER)

    SLE-Module-Certifications12-Pool
    SLE-Module-Certifications12-Updates
Modules Available for SLES 12 SP2/SP3
  • HPC Module: tools and libraries related to High Performance Computing

    SLE-Module-HPC12-Pool
    SLE-Module-HPC12-Updates

18.6.4 Required Repositories for SUSE Linux Enterprise Desktop

SLED 11 SP3
SLED11-SP3-Pool
SLED11-SP3-Updates
SLED 11 SP4
SLED11-SP4-Pool
SLED11-SP4-Updates
SLED 12
SLED12-GA-Pool
SLED12-GA-Updates
SLED 12 SP1
SLED12-SP1-Pool
SLED12-SP1-Updates
SLED 12 SP2
SLED12-SP2-Pool
SLED12-SP2-Updates
SLED 12 SP3
SLED12-SP3-Pool
SLED12-SP3-Updates

18.6.5 Optional Repositories for SUSE Linux Enterprise Desktop

SLED 11 SP3
SLED11-SP3-Debuginfo-Core
SLED11-SP3-Debuginfo-Updates
SLED11-SP3-Extension-Store
SLED11-SP3-Extra
SLED 12
SLED12-GA-Debuginfo-Core
SLED12-GA-Debuginfo-Updates
SLED 12 SP1
SLED12-SP1-Debuginfo-Core
SLED12-SP1-Debuginfo-Updates
SLED 12 SP2
SLED12-SP2-Debuginfo-Core
SLED12-SP2-Debuginfo-Updates
SLED 12 SP3
SLED12-SP3-Debuginfo-Core
SLED12-SP3-Debuginfo-Updates

18.6.6 Origin of Packages

SUSE Linux Enterprise 11 SP3/SP4.  With the update to SP3 there are only two repositories available: SLES11-SP3-Pool and SLES11-SP3-Updates. Since SP4, any previous repositories are not visible anymore.

SUSE Linux Enterprise 12 and SP1/SP2.  With the update to SUSE Linux Enterprise 12 there are only two repositories available: SLES12-GA-Pool and SLES12-GA-Updates. Any previous repositories from SUSE Linux Enterprise 11 are not visible anymore.

18.6.7 Register and Unregister Repositories with SUSEConnect

On registration, the system receives repositories from the SUSE Customer Center (see https://scc.suse.com/) or a local registration proxy like SMT. The repository names map to specific URIs in the customer center. To list all available repositories on your system, use zypper as follows:

root # zypper repos -u

This gives you a list of all available repositories on your system. Each repository is listed by its alias, name and whether it is enabled and will be refreshed. The option -u gives you also the URI from where it originated.

To register your machine, run SUSEConnect, for example:

root # SUSEConnect -r REGCODE

If you want to unregister your machine, from SP1 and above you can use SUSEConnect too:

root # SUSEConnect --de-register

To check your locally installed products and their status, use the following command:

root # SUSEConnect -s

19 Upgrading SUSE Linux Enterprise

  • Filename: sle_update_upgrading.xml
  • ID: cha.update.sle
Abstract

SUSE® Linux Enterprise (SLE) allows to upgrade an existing system to the new version, for example, going from SLE 11 SP4 to the latest SLE 12 service pack. No new installation is needed. Existing data, such as home and data directories and system configuration, is kept intact. You can update from a local CD or DVD drive or from a central network installation source.

This chapter explains how to manually upgrade your SUSE Linux Enterprise system, be it by DVD, network, an automated process, or SUSE Manager.

19.1 Supported Upgrade Paths to SLE 12 SP3

Important
Important: Cross-architecture Upgrades Are Not Supported

Cross-architecture upgrades, such as upgrading from a 32-bit version of SUSE Linux Enterprise Server to the 64-bit version, or upgrading from big endian to little endian are not supported!

Specifically, SLE 11 on POWER (big endian) to SLE 12 SP2 on POWER (new: little endian!), is not supported.

Also, since SUSE Linux Enterprise 12 is 64-bit only, upgrades from any 32-bit SUSE Linux Enterprise 11 systems to SUSE Linux Enterprise 12 and later are not supported.

To make a cross-architecture upgrade, you need to perform a new installation.

Before you perform any migration, read Section 19.3, “Preparing the System”.

Note
Note: Skipping Service Packs

Consecutively installing all Service Packs is the safest upgrade path. In some cases it is supported to skip 1 or 2 Service Packs when upgrading. However, we recommend to not skip any Service Pack.

Note
Note: Upgrading Major Releases

We recommend to do a fresh install when upgrading to a new Major Release, for example from SUSE Linux Enterprise 11 to SUSE Linux Enterprise 12.

Upgrading from SUSE Linux Enterprise 10 (any Service Pack)

There is no supported direct migration path to SUSE Linux Enterprise 12. We recommend a fresh installation in this case.

Upgrading from SUSE Linux Enterprise 11 GA / SP1 / SP2 / SP3

There is no supported direct migration path to SUSE Linux Enterprise 12. You need at least SLE 11 SP4 before you can proceed to SLE 12 SP3.

If you cannot do a fresh install, first upgrade your installed SLE 11 Service Pack to SLE 11 SP4. These steps are described in the SUSE Linux Enterprise 11 Deployment Guide.

Upgrading from SUSE Linux Enterprise 11 SP4

Upgrading from SLE 11 SP4 to SLE 12 SP3 is only supported via an offline upgrade. Refer to Section 19.2, “Online and Offline Upgrade” for details.

Upgrading from SUSE Linux Enterprise 12 GA to SP3

A direct upgrade from SLE 12 GA to SP3 is not supported. Upgrade to SLE 12 SP2 first.

Upgrading from SUSE Linux Enterprise 12 SP1 / SP2 to SP3

Upgrading from SUSE Linux Enterprise 12 SP1 or SP2 to SP3 is supported.

Upgrading from SUSE Linux Enterprise 12 LTSS GA / SP1 LTSS / SP2 to SP3

Updating any previous SLE 12 LTSS version to SP3 is supported.

Overview of Shortest Upgrade Paths
Figure 19.1: Overview of Shortest Upgrade Paths

19.2 Online and Offline Upgrade

SUSE supports two different upgrade and migration methods. For more information about the terminology, see Section 18.1, “Terminology”. The methods are:

Online

All upgrades that are executed from the running system are considered to be online. Examples: Connected through SUSE Customer Center, Subscription Management Tool (SMT), SUSE Manager using Zypper or YaST.

When migrating between Service Packs of the same major release, we suggest following Section 21.4, “Upgrading with the Online Migration Tool (YaST)” or Section 21.5, “Upgrading with Zypper”.

Offline

Offline methods usually boot another operating system from which the installed SLE version is upgraded. Examples are: DVD, flash disk, ISO image, AutoYaST, plain RPM or PXE boot.

Upgrading from SUSE Linux Enterprise 11 SP4 to SUSE Linux Enterprise 12 SP3 is only supported via an offline upgrade. See Chapter 20, Upgrading Offline

Upgrading from any SUSE Linux Enterprise 12 LTSS version or SUSE Linux Enterprise 12 SP1 or SP2 to SP3 is supported using all offline and online methods. See Chapter 20, Upgrading Offline and Chapter 21, Upgrading Online.

19.3 Preparing the System

Before starting the upgrade procedure, make sure your system is properly prepared. Among others, preparation involves backing up data and checking the release notes.

19.3.1 Make Sure the Current System is Up-To-Date

Upgrading the system is only supported from the most recent patch-level. Make sure the latest system updates are installed by either running zypper patch or by starting the YaST module Online-Update.

19.3.2 Read the Release Notes

In the release notes you can find additional information on changes since the previous release of SUSE Linux Enterprise Server. Check the release notes to see whether:

  • your hardware needs special considerations;

  • any used software packages have changed significantly;

  • special precautions are necessary for your installation.

The release notes also provide information that could not make it into the manual on time. They also contain notes about known issues.

If you are skipping one or more Service Packs, check the release notes of the skipped Service Packs as well. The release notes usually only contain the changes between two subsequent releases. You can miss important changes if you are only reading the current release notes.

Find the release notes locally in the directory /usr/share/doc/release-notes or online at https://www.suse.com/releasenotes/.

19.3.3 Make a Backup

Before updating, copy existing configuration files to a separate medium (such as tape device, removable hard disk, etc.) to back up the data. This primarily applies to files stored in /etc and some directories and files in /var and /opt. You may also want to write the user data in /home (the HOME directories) to a backup medium. Back up this data as root. Only root has read permissions for all local files.

If you have selected Update an Existing System as the installation mode in YaST, you can choose to do a (system) backup at a later point in time. You can choose to include all modified files and files from the /etc/sysconfig directory. However, this is not a complete backup, as all the other important directories mentioned above are missing. Find the backup in the /var/adm/backup directory.

19.3.3.1 Listing Installed Packages and Repositories

It is often useful to have a list of installed packages, for example when doing a fresh install of a new major SLE release or reverting to the old version.

Be aware that not all installed packages or used repositories are available in newer releases of SUSE Linux Enterprise. Some may have been renamed and others replaced. It is also possible that some packages are still available for legacy purposes while another package is used by default. Therefore some manual editing of the files might be necessary. This can be done with any text editor.

Create a file named repositories.bak containing a list of all used repositories:

root # zypper lr -e repositories.bak

Also create a file named installed-software.bak containing a list of all installed packages:

root # rpm -qa --queryformat '%{NAME}\n' > installed-software.bak

Back up both files. The repositories and installed packages can be restored with the following commands:

root # zypper ar repositories.bak
root # zypper install $(cat installed-software.bak)
Note
Note: Amount of Packages Increases with an Update to a new Major Release

A system upgraded to a new major version (SLE X+1) may contain more packages than the initial system (SLE X). It will also contain more packages than a fresh installation of SLE X+1 with the same pattern selection. Reasons for this are:

  • Packages got split to allow a more fine-grained package selection. For example, 37 texlive packages on SLE 11 were split into 422 packages on SLE 12.

  • When a package got split into other packages all new packages are installed in the upgrade case to retain the same functionality as with the previous version. However, the new default for a fresh installation of SLE X+1 may be to not install all packages.

  • Legacy packages from SLE X may be kept for compatibility reasons.

  • Package dependencies and the scope of patterns may have changed.

19.3.4 Migrate your MySQL Database

As of SUSE Linux Enterprise 12, SUSE switched from MySQL to MariaDB. Before you start any upgrade, it is highly recommended to back up your database.

To perform the database migration, do the following:

  1. Log in to your SUSE Linux Enterprise 11 machine.

  2. Create a dump file:

    root # mysqldump -u root -p --all-databases > mysql_backup.sql

    By default, mysqldump does not dump the INFORMATION_SCHEMA or performance_schema database. For more details refer to https://dev.mysql.com/doc/refman/5.5/en/mysqldump.html.

  3. Store your dump file, the configuration file /etc/my.cnf, and the directory /etc/mysql/ for later investigation (NOT installation!) in a safe place.

  4. Perform your upgrade. After the upgrade, your former configuration file /etc/my.cnf is still intact. You can find the new configuration in the file /etc/my.cnf.rpmnew.

  5. Configure your MariaDB database to your needs. Do NOT use the former configuration file and directory, but use it as a reminder and adapt it.

  6. Make sure you start the MariaDB server:

    root # systemctl start mysql

    If you want to start the MariaDB server on every boot, enable the service:

    root # systemctl enable mysql
  7. Verify that MariaDB is running properly by connecting to the database:

    root # mysql -u root -p

19.3.5 Migrate your PostgreSQL Database

SLE11 SP3 and SLE12 GA get a newer version of the PostgreSQL database as a maintenance update. Because of the required migration work of the database, there is no automatic upgrade process. As such, the switch from one version to another needs to be done manually.

The migration process is conducted by the pg_upgrade command which is an alternative method of the classic dump and reload. In comparison with the dump & reload method, pg_upgrade makes the migration less time-consuming.

Each PostgreSQL version stores its files in different, version-dependent directories. After the update the directories will change to:

SLE11 SP3/SP4

/usr/lib/postgresql91/ to /usr/lib/postgresql94/

SLE12 GA

/usr/lib/postgresql93/ to /usr/lib/postgresql94/

To perform the database migration, do the following:

  1. Make sure the following preconditions are fulfilled:

    • If not already done, upgrade any package of the old PostgreSQL version to the latest release through a maintenance update.

    • Create a backup of your existing database.

    • Install the packages of the new PostgreSQL major version. For SLE12 this means to install postgresql94-server and all the packages it depends on.

    • Install the package postgresql94-contrib which contains the command pg_upgrade.

    • Make sure you have enough free space in your PostgreSQL data area, which is /var/lib/pgsql/data by default. If space is tight, try to reduce size with the following SQL command on each database (can take very long!):

      VACUUM FULL
  2. Stop the PostgreSQL server:

    root # /usr/sbin/rcpostgresql stop
  3. Rename your old data directory:

    root # mv /var/lib/pgsql/data /var/lib/pgsql/data.old
  4. Create a new data directory:

    root # mkdir -p /var/lib/pgsql/data
  5. If you have changed your configuration files in the old version, copy the files postgresql.conf pg_hba.conf to your new data directory:

    root # cp /var/lib/pgsql/data.old/*.conf \
         /var/lib/pgsql/data
  6. Initialize your new database instance either manually with initdb or by starting and stopping PostgreSQL, which will do it automatically:

    root # /usr/sbin/rcpostgresql start
    root # /usr/sbin/rcpostgresql stop
  7. Start the migration process and replace the OLD placeholder with the older version:

    root # pg_upgrade \
       --old-datadir "/var/lib/pgsql/data.old" \
       --new-datadir "/var/lib/pgsql/data" \
       --old-bindir "/usr/lib/postgresqlOLD/bin/" \
       --new-bindir "/usr/lib/postgresql94/bin/"
  8. Start your new database instance:

    root # /usr/sbin/rcpostgresql start
  9. Check if the migration was successful. There is no general tool to automate this step. It depends on your use case how much and what you want to test.

  10. Remove any old PostgreSQL packages and your old data directory:

    root # zypper search -s postgresqlOLD | xargs zypper rm -u
    root # rm -rf /var/lib/pgsql/data.old

19.3.6 Create Non-MD5 Server Certificates for Java Applications

During the update from SP1 to SP2, MD5-based certificates were disabled as part of a security fix. If you have certificates created as MD5, re-create your certificates with the following steps:

  1. Open a terminal and log in as root.

  2. Create a private key:

    root # openssl genrsa -out server.key 1024

    If you want a stronger key, replace 1024 with a higher number, for example, 4096.

  3. Create a certificate signing request (CSR):

    root # openssl req -new -key server.key -out server.csr
  4. Self-sign the certificate:

    root # openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
  5. Create the PEM file:

    root # cat server.key server.crt > server.pem
  6. Place the files server.crt, server.csr, server.key, and server.pem in the respective directories where the keys can be found. For Tomcat, for example, this directory is /etc/tomcat/ssl/.

19.3.7 Shut Down Virtual Machine Guests

If your machine serves as a VM Host Server for KVM or Xen, make sure to properly shut down all running VM Guests prior to the update. Otherwise you may not be able to access the guests after the update.

19.3.8 Check the clientSetup4SMT.sh Script on SMT Clients

If you are migrating your client OS that is registered against an SMT server, you need to check if the version of the clientSetup4SMT.sh script on your host is up to date. clientSetup4SMT.sh from older versions of SMT cannot manage SMT 12 clients. If you apply software patches regularly on your SMT server, you can always find the latest version of clientSetup4SMT.sh at <SMT_HOSTNAME>/repo/tools/clientSetup4SMT.sh.

19.3.9 Disk Space

Software tends to grow from version to version. Therefore, take a look at the available partition space before updating. If you suspect you are running short of disk space, back up your data before increasing the available space by resizing partitions, for example. There is no general rule regarding how much space each partition should have. Space requirements depend on your particular partitioning profile and the software selected.

Note
Note: Automatic Check for Enough Space in YaST

During the update procedure, YaST will check how much free disk space is available and display a warning to the user if the installation may exceed the available amount. In that case, performing the update may lead to an unusable system! Only if you know exactly what you are doing (by testing beforehand), you can skip the warning and continue the update.

19.3.9.1 Checking Disk Space on Non-Btrfs File Systems

Use the df command to list available disk space. For example, in Example 19.1, “List with df -h, the root partition is /dev/sda3 (mounted as /).

Example 19.1: List with df -h
Filesystem     Size  Used Avail Use% Mounted on
/dev/sda3       74G   22G   53G  29% /
tmpfs          506M     0  506M   0% /dev/shm
/dev/sda5      116G  5.8G  111G   5% /home
/dev/sda1       44G    4G   40G   9% /data

19.3.9.2 Checking Disk Space on Btrfs Root File Systems

If you use Btrfs as root file systems on your machine, make sure there is enough free space. In the worst case, an upgrade needs as much disk space as the current root file system (without /.snapshot) for a new snapshot. To display available disk space use the command:

root # df -h /

Check the available space on all other mounted partitions as well. The following recommendations have been proven:

  • For all file systems including Btrfs you need enough free disk space to download and install big RPMs. The space of old RPMs are only freed after new RPMs are installed.

  • For Btrfs with snapshots, you need at minimum as much free space as your current installation takes. We recommend to have twice as much free space as the current installation.

    If you do not have enough free space, you can try to delete old snapshots with snapper:

    root # snapper list
    root # snapper delete NUMBER

    However, this may not help in all cases. Before migration, most snapshots occupy only little space.

19.3.10 Temporarily Disabling Kernel Multiversion Support

SUSE Linux Enterprise Server allows installing multiple kernel versions by enabling the respective settings in /etc/zypp/zypp.conf. Support for this feature needs to be temporarily disabled to upgrade to a service pack. When the update has successfully finished, multiversion support can be re-enabled. To disable multiversion support, comment the respective lines in /etc/zypp/zypp.conf. The result should look similar to:

#multiversion = provides:multiversion(kernel)
#multiversion.kernels = latest,running

To re-activate this feature after a successful update, remove the comment signs. For more information about multiversion support, refer to Section 15.1, “Enabling and Configuring Multiversion Support”.

19.4 Upgrading on IBM z Systems

Upgrading a SUSE Linux Enterprise installation on z Systems requires the Upgrade=1 kernel parameter, for example via the parmfile. See Section 4.3, “The parmfile—Automating the System Configuration”.

19.5 IBM POWER: Starting an X Server

On SLES 12 for IBM POWER the display manager is configured not to start a local X Server by default. This setting was reversed on SLES 12 SP1—the display manager now starts an X Server.

To avoid problems during upgrade, the SUSE Linux Enterprise Server setting is not changed automatically. If you want the display manager to start an X Server after the upgrade, change the setting of DISPLAYMANAGER_STARTS_XSERVER in /etc/sysconfig/displaymanager as follows:

DISPLAYMANAGER_STARTS_XSERVER="yes"

20 Upgrading Offline

  • Filename: sle_update_offline.xml
  • ID: cha.update.offline
Abstract

This chapter describes how to upgrade an existing SUSE Linux Enterprise installation using YaST which is booted from an installation medium. The YaST installer can, for example, be started from a DVD, over the network, or from the hard disk the system resides on.

20.1 Conceptual Overview

Before upgrading your system, read Section 19.3, “Preparing the System” first.

To upgrade your system, boot from an installation source, as you would do for a fresh installation. However, when the boot screen appears, you need to select Upgrade (instead of Installation). The upgrade can be started from:

20.2 Starting the Upgrade from Installation Medium

The procedure below describes booting from a DVD, but you can also use another local installation medium like an ISO image on a USB mass storage device. The medium and boot method to select depends on the system architecture and on whether the machine has a traditional BIOS or UEFI.

Procedure 20.1: Manually Upgrading from SLE 11 SP4 to SLE 12 SP3
  1. Select and prepare a boot medium, see Section 6.2, “System Start-up for Installation”.

  2. Insert DVD 1 of the SUSE Linux Enterprise 12 SP3 installation medium and boot your machine. A Welcome screen is displayed, followed by the boot screen.

  3. Start up the system by selecting Upgrade in the boot menu.

  4. Proceed with the upgrade process as described in Section 20.6, “Upgrading SUSE Linux Enterprise”.

20.3 Starting Upgrade from Network Source

To start an upgrade from a network installation source, make sure that the following requirements are met:

Requirements for Upgrading from a Network Installation Source
Network Installation Source

A network installation source is set up according to Chapter 8, Setting Up the Server Holding the Installation Sources.

Network Connection and Network Services

Both the installation server and the target machine must have a functioning network connection. Required network services are:

  • Domain Name Service

  • DHCP (only needed for booting via PXE, IP can be set manually during setup)

  • OpenSLP (optional)

Boot Medium

You have a SUSE Linux Enterprise Server DVD 1 (or a local ISO image) at hand to boot the target system or a target system that is set up for booting via PXE according to Section 9.5, “Preparing the Target System for PXE Boot”. Refer to Chapter 10, Remote Installation for in-depth information on starting the upgrade from a remote server.

20.3.1 Manually Upgrading via Network Installation Source—Booting from DVD

This procedure describes booting from a DVD as an example, but you can also use another local installation medium like an ISO image on a USB mass storage device. The way to select the boot method and to start up the system from the medium depends on the system architecture and on whether the machine has a traditional BIOS or UEFI. For details, see the links below.

  1. Insert DVD 1 of the SUSE Linux Enterprise 12 SP2 installation media and boot your machine. A Welcome screen is displayed, followed by the boot screen.

  2. Select the type of network installation source you want to use (FTP, HTTP, NFS, SMB, or SLP). Usually you get this choice by pressing F4, but in case your machine is equipped with UEFI instead of a traditional BIOS, you may need to manually adjust boot parameters. For details, see Installing from a Network Server in Chapter 6, Installation with YaST.

  3. Proceed with the upgrade process as described in Section 20.6, “Upgrading SUSE Linux Enterprise”.

20.3.2 Manually Upgrading via Network Installation Source—Booting via PXE

To perform an upgrade from a network installation source using PXE boot, proceed as follows:

  1. Adjust the setup of your DHCP server to provide the address information needed for booting via PXE. For details, see Section 9.5, “Preparing the Target System for PXE Boot”.

  2. Set up a TFTP server to hold the boot image needed for booting via PXE. Use DVD 1 of your SUSE Linux Enterprise 12 SP2 installation media for this or follow the instructions in Section 9.2, “Setting Up a TFTP Server”.

  3. Prepare PXE Boot and Wake-on-LAN on the target machine.

  4. Initiate the boot of the target system and use VNC to remotely connect to the installation routine running on this machine. For more information, see Section 10.3.1, “VNC Installation”.

  5. Proceed with the upgrade process as described in Section 20.6, “Upgrading SUSE Linux Enterprise”.

20.4 Starting Upgrade from Hard Disk

20.4.1 Automated Migration from SUSE Linux Enterprise 11 SP3 or SP4 to SUSE Linux Enterprise 12 SP2

  1. Copy the installation kernel linux and the file initrd from /boot/x86_64/loader/ from your first installation DVD to your system's /boot directory:

    root # cp -vi DVDROOT/boot/x86_64/loader/linux /boot/linux.upgrade
    root # cp -vi DVDROOT/boot/x86_64/loader/initrd /boot/initrd.upgrade

    DVDROOT denotes the path where your system mounts the DVD, usually /run/media/$USER/$DVDNAME.

  2. Open the GRUB legacy configuration file /boot/grub/menu.lst and add another section. For other boot loaders, edit the respective configuration file(s). Adjust device names and the root parameter accordingly. For example:

    title Linux Upgrade Kernel
    kernel (hd0,0)/boot/linux.upgrade root=/dev/sda1 upgrade=1 autoupgrade=1
    initrd (hd0,0)/boot/initrd.upgrade
  3. The following steps either need the DVD in the drive or the ISO image has to be present on the local disk. If the computer has no DVD drive, either download the ISO and save it as /install.iso or copy it from the DVD.

    root # dd if=/dev/cdrom of=/install.iso

    If you copied the ISO to your hard disk, you need to add a parameter to the previously edited /boot/grub/menu.lst. To the line beginning with kernel add the option

    install=hd:/install.iso
  4. Reboot your machine and select the newly added section from the boot menu (here: Linux Upgrade Kernel). You can use grubonce to preselect the newly created GRUB entry for an unattended automatic reboot into the newly created entry. You can also use reboot to initiate the reboot from the command line.

  5. Proceed with the upgrade process as described in Section 20.6, “Upgrading SUSE Linux Enterprise”.

  6. After the upgrade process was finished successfully, remove the installation kernel and initrd files (/boot/linux.upgrade and /boot/initrd.upgrade). They are not needed anymore.

20.5 Enabling Automatic Upgrade

The upgrade process can be executed automatically. To enable the automatic update, the kernel parameter autoupgrade=1 must be set. The parameter can be set on boot in the Boot Options field. For details, see https://www.suse.com/documentation/sles-12/book_autoyast/data/introduction.html.

20.6 Upgrading SUSE Linux Enterprise

Before you upgrade your system, read Section 19.3, “Preparing the System” first. To perform an automated migration, proceed as follows:

  1. After you have booted (either from an installation medium or the network), select the Upgrade entry on the boot screen. If you want to do the upgrade as described in the next steps manually, you need to disable the automatic upgrade process. Refer to Section 20.5, “Enabling Automatic Upgrade”.

    Warning
    Warning: Wrong Choice May Lead to Data Loss

    If you select Installation instead of Upgrade, data may be lost later. You need to be extra careful not to destroy your data partitions by doing a fresh installation.

    Make sure to select Upgrade here.

    YaST starts the installation system.

  2. On the Welcome screen, choose Language and Keyboard and accept the license agreement. Proceed with Next.

    YaST checks your partitions for already installed SUSE Linux Enterprise systems.

  3. On the Select for Upgrade screen, select the partition to upgrade and click Next.

    YaST mounts the selected partition and displays all repositories that have been found on the partition that you want to upgrade.

  4. On the Previously Used Repositories screen, adjust the status of the repositories: enable those you want to include in the upgrade process and disable any repositories that are no longer needed. Proceed with Next.

  5. On the Registration screen, select whether to register the upgraded system now (by entering your registration data and clicking Next) or if to Skip Registration. For details on registering your system, see Section 20.9, “Registering Your System”.

  6. Review the Installation Settings for the upgrade, especially the Update Options. Choose between the following options:

    • Only Update Installed Packages, in which case you might miss new features shipped with the latest SUSE Linux Enterprise version.

    • Update with Installation of New Software and Features. Click Select Patterns if you want to enable or disable patterns and packages according to your wishes.

    Note
    Note: Choice of Desktop

    If you used KDE before upgrading to SUSE Linux Enterprise 12 (DEFAULT_WM in /etc/sysconfig/windowmanager was set to kde*), your desktop environment will automatically be replaced with GNOME after the upgrade. By default, the KDM display manager will be replaced with GDM.

    To change the choice of desktop environment or window manager, adjust the software selection by clicking Select Patterns.

  7. If all settings are according to your wishes, start the installation and removal procedure by clicking Update.

  8. After the upgrade process was finished successfully, check for any orphaned packages. Orphaned packages are packages which belong to no active repository anymore. The following command gives you a list of these:

    zypper packages --orphaned

    With this list, you can decide if a package is still needed or can be uninstalled safely.

20.7 Updating via SUSE Manager

SUSE Manager is a server solution for providing updates, patches, and security fixes for SUSE Linux Enterprise clients. It comes with a set of tools and a Web-based user interface for management tasks. See https://www.suse.com/products/suse-manager/ for more information about SUSE Manager.

SUSE Manager can support you with SP Migration or a full system upgrade.

SP Migration

SP Migration allows migrating from one Service Pack (SP) to another within one major version (for example, from SLES 12 SP1 to 12 SP2). For more information, see the SUSE Manager Best Practices, chapter Client Migration, section Migrating SUSE Linux Enterprise Server 12 or later to version 12 SP2:

https://www.suse.com/documentation/suse-manager/, version 3.1.

System Upgrade

With SUSE Manager you can perform a system upgrade. With the integrated AutoYaST technology, upgrades from one major version to the next are possible (for example, from SLES 11 SP3 to 12 SP2). For more information, see the SUSE Manager Best Practices, chapter Client Migration, section Migrating SUSE Linux Enterprise 11 SP3 to version 12 SP2:

https://www.suse.com/documentation/suse-manager/, version 3.1.

20.8 Updating Registration Status after Rollback

When performing a service pack upgrade, it is necessary to change the configuration on the registration server to provide access to the new repositories. If the upgrade process is interrupted or reverted (via restoring from a backup or snapshot), the information on the registration server is inconsistent with the status of the system. This may lead to you being prevented from accessing update repositories or to wrong repositories being used on the client.

When a rollback is done via Snapper, the system will notify the registration server to ensure access to the correct repositories is set up during the boot process. If the system was restored any other way or the communication with the registration server failed for any reason (for example, because the server was not accessible because of network issues), trigger the rollback on the client manually by calling:

snapper rollback

We suggest always checking that the correct repositories are set up on the system, especially after refreshing the service using:

zypper ref -s

This functionality is available in the rollback-helper package.

20.9 Registering Your System

If you skipped the registration step during the installation, you can register your system at any time using the Product Registration module in YaST.

Registering your systems has these advantages:

  • Eligibility for support

  • Availability of security updates and bug fixes

  • Access to SUSE Customer Center

  1. Start YaST and select Software › Product Registration to open the Registration dialog.

  2. Provide the E-mail address associated with the SUSE account you or your organization uses to manage subscriptions. In case you do not have a SUSE account yet, go to the SUSE Customer Center home page (https://scc.suse.com/) to create one.

  3. Enter the Registration Code you received with your copy of SUSE Linux Enterprise Server.

  4. To start the registration, proceed with Next. If one or more local registration servers are available on your network, you can choose one of them from a list. Alternatively, to ignore the local registration servers and register with the default SUSE registration server, choose Cancel.

    During the registration, the online update repositories will be added to your upgrade setup. When finished, you can choose whether to install the latest available package versions from the update repositories. This provides a clean upgrade path for all packages and ensures that SUSE Linux Enterprise Server is upgraded with the latest security updates available. If you choose No, all packages will be installed from the installation media. Proceed with Next.

    After successful registration, YaST lists extensions, add-ons, and modules that are available for your system. To select and install them, proceed with Section 14.2, “Installing Modules and Extensions from Online Channels”.

21 Upgrading Online

  • Filename: sle_update_online.xml
  • ID: cha.update.online
Abstract

SUSE offers an intuitive graphical and a simple command line tool to upgrade a running system to a new service pack. They provide support for rollback of service packs and more. This chapter explains how to do a service pack upgrade step by step with these tools.

21.1 Conceptual Overview

SUSE releases new service packs for the SUSE Linux Enterprise family at regular intervals. To make it easy for customers to migrate to a new service pack and minimize downtime, SUSE supports migrating online while the system is running.

Starting with SLE 12, YaST Wagon has been replaced by YaST migration (GUI) and Zypper migration (command line). The following features are supported:

  • System always in a defined state until the first RPM is updated

  • Canceling is possible until the first RPM is updated

  • Simple recovery, if there is an error

  • Rollback via system tools; no backup/restore needed

  • Use of all active repositories

  • The ability to skip a service pack

21.2 Service Pack Migration Workflow

A service pack migration can be executed by either YaST, zypper, or AutoYaST.

Before you can start a service pack migration, your system must be registered at the SUSE Customer Center or a local SMT server. SUSE Manager can also be used.

Regardless of the method, a service pack migration consists of the following steps:

  1. Find possible migration targets on your registered systems.

  2. Select one migration target.

  3. Request and enable new repositories.

  4. Run the migration.

The list of migration targets depends on the products you have installed and registered. If you have an extension installed for which the new SP is not yet available, it could be that no migration target is offered to you.

The list of migration targets available for your host will always be retrieved from the SUSE Customer Center and depend on products or extensions installed.

21.3 Canceling Service Pack Migration

A service pack migration can only be cancelled at specific stages during the migration process:

  1. Until the package upgrade starts, there are only minimal changes on the system, like for services and repositories. Restore /etc/zypp/repos.d/* to revert to the former state.

  2. After the package upgrade starts, you can revert to the former state by using a Snapper snapshot (see Chapter 7, System Recovery and Snapshot Management with Snapper).

  3. After the migration target was selected, SUSE Customer Center changes the repository data. To revert this state manually, use SUSEConnect --rollback.

21.4 Upgrading with the Online Migration Tool (YaST)

To perform a service pack migration with YaST, use the Online Migration tool. By default, YaST does not install any packages from a third-party repository. If a package was installed from a third-party repository, YaST prevents packages from being replaced with the same package coming from SUSE.

Note
Note: Reduce Installation Size

When performing the SP migration, YaST will install all recommended packages. Especially in the case of custom minimal installations, this may increase the installation size of the system significantly.

To change this default behavior and allow only required packages, adjust /etc/zypp/zypp.conf and set the following variable:

solver.onlyRequires = true
installRecommends=false # or commented

This changes the behavior of all package operations, such as the installation of patches or new packages.

To start the service pack migration, do the following:

  1. Deactivate all unused extensions on your registration server to avoid future dependency conflicts. In case you forget an extension, YaST will later detect unused extension repositories and deactivate them.

  2. If you are logged in to a GNOME session running on the machine you are going to update, switch to a text console. Running the update from within a GNOME session is not recommended. Note that this does not apply when being logged in from a remote machine (unless you are running a VNC session with GNOME).

  3. If you are an LTSS subscriber, make sure that the LTSS extension repository is active.

  4. Run YaST online update to get the latest package updates for your system.

  5. Install the package yast2-migration and its dependencies (in YaST under Software › Software Management).

  6. Restart YaST, otherwise the newly installed module will not be shown in the control center.

  7. In YaST, choose Online Migration (depending on the version of SUSE Linux Enterprise Server that you are upgrading from, this module is categorized under either System or Software). YaST will show possible migration targets and a summary. If more than one migration target is available for your system, select one from the list.

  8. Select one migration target from the list and proceed with Next.

  9. In case the migration tool offers update repositories, it is recommended to proceed with Yes.

  10. If the Online Migration tool finds obsolete repositories coming from DVD or a local server, it is highly recommended to disable them. Obsolete repositories are from a previous SP. Any old repositories from SCC or SMT are removed automatically.

  11. Check the summary and proceed with the migration by clicking Next. Confirm with Start Update.

  12. After the successful migration restart your system.

21.5 Upgrading with Zypper

To perform a service pack migration with Zypper, use the command line tool zypper migration from the package zypper-migration-plugin.

Note
Note: Reduce Installation Size

When performing the SP migration, YaST will install all recommended packages. Especially in the case of custom minimal installations, this may increase the installation size of the system significantly.

To change this default behavior and allow only required packages, adjust /etc/zypp/zypp.conf and set the following variable:

solver.onlyRequires = true
installRecommends=false # or commented

This changes the behavior of all package operations, such as the installation of patches or new packages. To change the behavior of Zypper for a single invocation, add the parameter --no-recommends to your command line.

To start the service pack migration, do the following:

  1. If you are logged in to a GNOME session running on the machine you are going to update, switch to a text console. Running the update from within a GNOME session is not recommended. Note that this does not apply when being logged in from a remote machine (unless you are running a VNC session with GNOME).

  2. Register your SUSE Linux Enterprise machine if you have not done so:

    sudo SUSEConnect --regcode YOUR_REGISTRATION_CODE
  3. If you are an LTSS subscriber, make sure that the LTSS extension repository is active.

  4. Install the latest updates:

    sudo zypper patch
  5. Install the zypper-migration-plugin package and its dependencies:

    sudo zypper in zypper-migration-plugin
  6. Run zypper migration:

    tux > sudo zypper migration
    Executing 'zypper  patch-check'
    
    Refreshing service 'SUSE_Linux_Enterprise_Server_12_x86_64'.
    Loading repository data...
    Reading installed packages...
    0 patches needed (0 security patches)
    
    Available migrations:
    
        1 | SUSE Linux Enterprise Server 12 SP1 x86_64
        2 | SUSE Linux Enterprise Server 12 SP2 x86_64

    Some notes about the migration process:

    • If more than one migration target is available for your system, Zypper allows you to select one SP from the list. This is the same as skipping one or more SPs. Keep in mind, online migration for base products (SLES, SLED) remains available only between the SPs of a major version.

    • By default, Zypper uses the option --no-allow-vendor-change which is passed to zypper dup. If a package was installed from a third-party repository, this option prevents packages from being replaced with the same package coming from SUSE.

    • If Zypper finds obsolete repositories coming from DVD or a local server, it is highly recommended to disable them. Old SCC or SMT repositories are removed automatically.

  7. Review all the changes, especially the packages that are going to be removed. Proceed by typing y (the exact number of packages to upgrade can vary on your system):

    266 packages to upgrade, 54 to downgrade, 17 new, 8 to reinstall, 5 to remove, 1 to change arch.
    Overall download size: 285.1 MiB. Already cached: 0 B  After the operation, additional 139.8 MiB will be used.
    Continue? [y/n/? shows all options] (y):

    Use the ShiftPage ↑ or ShiftPage ↓ keys to scroll in your shell.

  8. After successful migration restart your system.

21.6 Upgrading with Plain Zypper

If you cannot use YaST migration or the Zypper migration, you can still migrate with plain Zypper and some manual interactions. To start a service pack migration, do the following:

  1. If you are logged in to a GNOME session running on the machine you are going to update, switch to a text console. Running the update from within a GNOME session is not recommended. Note that this does not apply when being logged in from a remote machine (unless you are running a VNC session with GNOME).

  2. Update the package management tools with the old SUSE Linux Enterprise repositories:

    sudo zypper patch --updatestack-only
  3. If the system is registered, it needs to be deregistered:

    sudo SUSEConnect --de-register
  4. Remove the old installation sources and repositories and adjust the third-party repositories.

  5. Add the new installation sources, be it local or remote sources (for the placeholder REPOSITORY, refer to Section 18.6, “Repository Model”):

    sudo zypper addrepo REPOSITORY

    You can also use SUSE Customer Center or Subscription Management Tool. The command for SUSE Linux Enterprise 12 SP1 on x86-64 is:

    sudo SUSEConnect -p SLES/12.2/x86_64 OPTIONS

    Keep in mind, cross-architecture upgrades are not supported.

    Zypper will display a conflict between the old and new kernel. Choose Solution 1 to continue.

    Problem: product:SLES-12.2-0.x86_64 conflicts with kernel < 4.4 provided by kernel-default-VERSION
     Solution 1: Following actions will be done:
      replacement of kernel-default-VERSION with kernel-default-VERSION
      deinstallation of kernel-default-VERSION
     Solution 2: do not install product:SLES-12.2-0.x86_64
  6. Finalize the migration:

    sudo zypper ref -f -s
    sudo zypper dup --no-allow-vendor-change --no-recommends

    The first command will update all services and repositories. The second command performs a distribution upgrade. Here, the last two options are important: -no-allow-vendor-change ensures that third-party RPMs will not overwrite RPMs from the base system. The option --no-recommends ensures that packages deselected during initial installation will not be added again.

21.7 Rolling Back a Service Pack

If a service pack does not work for you, SUSE Linux Enterprise supports reverting the system to the state before the service pack migration was started. Prerequisite is a Btrfs root partition with snapshots enabled (this is the default when installing SLES 12). See Chapter 7, System Recovery and Snapshot Management with Snapper for details.

  1. Get a list of all Snapper snapshots:

    sudo snapper list

    Review the output to locate the snapshot that was created immediately before the service pack migration was started. The column Description contains a corresponding statement and the snapshot is marked as important in the column Userdata. Memorize the snapshot number from the column # and its date from the column Date.

  2. Reboot the system. From the boot menu, select Start boot loader from a read-only snapshot and then choose the snapshot with the date and number you memorized in the previous step. A second boot menu (the one from the snapshot) is loaded. Select the entry starting with SLES 12 and boot it.

  3. The system boots into the previous state with the system partition mounted read-only. Log in as root and check whether you have chosen the correct snapshot. Also make sure everything works as expected. Note that since the root file system is mounted read-only, restrictions in functionality may apply.

    In case of problems or if you have booted the wrong snapshot, reboot and choose a different snapshot to boot from—up to this point no permanent changes have been made. If the snapshot is correct and works as expected, make the change permanent by running the following command:

    snapper rollback

    Reboot afterward. On the boot screen, choose the default boot entry to reboot into the reinstated system.

  4. Check if the repository configuration has been properly reset. Furthermore, check if all products are properly registered. If either one is not the case, updating the system at a later point in time may no longer work, or the system may be updated using the wrong package repositories.

    Make sure the system can access the Internet before starting this procedure.

    1. Refresh services and repositories by running

      sudo zypper ref -fs
    2. Get a list of active repositories by running

      sudo zypper lr

      Carefully check the output of this command. No services and repositories that were added for the update should be listed. If you, for example, are rolling back from a service pack migration from SLES 12 SP1 to SLES 12 SP2, the list must not contain the repositories SLES12-SP2-Pool and SLES12-SP2-Updates, but rather the SP1 versions.

      If wrong repositories are listed, delete them and, if necessary, replace them with the versions matching your product or service pack version. For a list of repositories for the supported migration paths refer to Section 18.6, “Repository Model”.

    3. Last, check the registration status for all products installed by running

      SUSEConnect --status

      All products should be reported as being Registered. If this is not the case, repair the registration by running

      SUSEConnect --rollback

Now you have successfully reverted the system to the state that was captured immediately before the service pack migration was started.

22 Backporting Source Code

  • Filename: sle_update_backporting.xml
  • ID: cha.update.backporting
Abstract

SUSE extensively uses backports, for example for the migration of current software fixes and features into released SUSE Linux Enterprise packages. The information in this chapter explains why it can be misleading to compare version numbers to judge the capabilities and the security of SUSE Linux Enterprise software packages. This chapter also explains how SUSE keeps the system software secure and current while maintaining compatibility for your application software on top of SUSE Linux Enterprise products. You will also learn how to check which public security issues actually are addressed in your SUSE Linux Enterprise system software, and the current status of your software.

22.1 Reasons for Backporting

Upstream developers are primarily concerned with advancing the software they develop. Often they combine fixing bugs with introducing new features which have not yet received extensive testing and which may introduce new bugs.

For distribution developers, it is important to distinguish between:

  • bugfixes with a limited potential for disrupting functionality; and

  • changes that may disrupt existing functionality.

Usually, distribution developers do not follow all upstream changes when a package has become part of a released distribution. Usually they stick instead with the upstream version that they initially released and create patches based on upstream changes to fix bugs. This practice is known as backporting.

Distribution developers generally will only introduce a newer version of software in two cases:

  • when the changes between their packages and the upstream versions have become so large that backporting is no longer feasible, or

  • for software that inherently ages badly, like anti-malware software.

SUSE uses backports extensively as we strike a good balance between several concerns for enterprise software. The most important of them are:

  • Having stable interfaces (APIs) that software vendors can rely on when building products for use on SUSE's enterprise products.

  • Ensuring that packages used in the release of SUSE's enterprise products are of the highest quality and have been thoroughly tested, both in themselves and as part of the whole enterprise product.

  • Maintaining the various certifications of SUSE's enterprise products by other vendors, like certifications for Oracle or SAP products.

  • Allowing SUSE's developers to focus on making the next version of the product as good as they can make it, rather than them having to spread their focus thinly across a wide range of releases.

  • Keeping a clear view of what is in a particular enterprise release, so that our support can provide accurate and timely information about it.

22.2 Reasons against Backports

It is a general policy rule that no new upstream versions of a package are introduced into our enterprise products. This rule is not an absolute rule however. For certain types of packages, in particular anti-virus software, security concerns weigh heavier than the conservative approach that is preferable from the perspective of quality assurance. For packages in that class, occasionally newer versions are introduced into a released version of an enterprise product line.

Sometimes also for other types of packages the choice is made to introduce a new version rather than a backport. This is done when producing a backport is not economically feasible or when there is a very relevant technical reason to introduce the newer version.

22.3 The Implications of Backports for Interpreting Version Numbers

Because of the practice of backporting, one cannot simply compare version numbers to determine whether a SUSE package contains a fix for a particular issue or has had a particular feature added to it. With backporting, the upstream part of a SUSE package's version number merely indicates what upstream version the SUSE package is based on. It may contain bug fixes and features that are not in the corresponding upstream release, but that have been backported into the SUSE package.

One particular area where this limited value of version numbers when backporting is involved can cause problems is with security scanning tools. Some security vulnerability scanning tools (or particular tests in such tools) operate solely on version information. These tools and tests are therefore prone to generating false positives (when a piece of software is incorrectly identified as vulnerable) when backports are involved. When evaluating reports from security scanning tools, always check whether an entry is based on a version number or on an actual vulnerability test.

22.4 How to Check Which Bugs are Fixed and Which Features are Backported and Available

There are several locations where information regarding backported bug fixes and features are stored:

  • The package's changelog:

    rpm -q --changelog name-of-installed-package
    rpm -qp --changelog packagefile.rpm

    The output briefly documents the change history of the package.

  • The package changelog may contain entries like bsc#1234 (Bugzilla Suse.Com) that refer to bugs in SUSE's Bugzilla tracking system or links to other bugtracking systems. Because of confidentiality policies, not all such information may be accessible to you.

  • A package may contain a /usr/share/doc/PACKAGENAME/README.SUSE file which contains general, high-level information specific to the SUSE package.

  • The RPM source package contains the patches that were applied during the building of the regular binary RPMs as separate files that can be interpreted if you are familiar with reading source code. See Section 6.1.2.5, “Installing or Downloading Source Packages” for installing sources of SUSE Linux Enterprise software, see Section 6.2.5, “Installing and Compiling Source Packages” for building packages on SUSE Linux Enterprise and see the Maximum RPM book for the inner workings of SUSE Linux Enterprise software package builds.

  • For security bug fixes, consult the SUSE security announcements. These often refer to bugs through standardized names like CAN-2005-2495 which are maintained by the Common Vulnerabilities and Exposures (CVE) project.

A Documentation Updates

  • Filename: deployment_docupdates.xml
  • ID: app.deployment.docupdates

This chapter lists content changes for this document.

This manual was updated on the following dates:

A.1 January 2018 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)

General

A.2 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)

General
Chapter 6, Installation with YaST

In Section 6.6, “IBM z Systems: Disk Activation”, adjusted a link to point to a more appropriate section in the Storage Administration Guide (https://bugzilla.suse.com/show_bug.cgi?id=1042060).

Chapter 9, Preparing the Boot of the Target System
Chapter 14, Installing Modules, Extensions, and Third Party Add-On Products
Chapter 18, Life Cycle and Support
Chapter 19, Upgrading SUSE Linux Enterprise
Chapter 20, Upgrading Offline
Chapter 21, Upgrading Online
Bugfixes

A.3 April 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP2)

Chapter 4, Installation on IBM z Systems
Section 18.3, “Module Life Cycles”
Bugfixes

A.4 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)

General
  • The e-mail address for documentation feedback has changed to doc-team@suse.com.

  • The documentation for Docker has been enhanced and renamed to Docker Guide.

General Changes to this Guide
Chapter 3, Installation on IBM POWER
Chapter 4, Installation on IBM z Systems
Chapter 6, Installation with YaST
Chapter 18, Life Cycle and Support
Chapter 21, Upgrading Online
Bugfixes

A.5 March 2016 (Maintenance Release of SUSE Linux Enterprise Server 12 SP1)

Chapter 4, Installation on IBM z Systems
Chapter 12, Advanced Disk Setup

A.6 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)

General
  • SMT Guide is now part of the documentation for SUSE Linux Enterprise Server.

  • Add-ons provided by SUSE have been renamed as modules and extensions. The manuals have been updated to reflect this change.

  • Numerous small fixes and additions to the documentation, based on technical feedback.

  • The registration service has been changed from Novell Customer Center to SUSE Customer Center.

  • In YaST, you will now reach Network Settings via the System group. Network Devices is gone (https://bugzilla.suse.com/show_bug.cgi?id=867809).

Chapter 2, Installation on AMD64 and Intel 64
  • Removed pointers to the Failsafe boot option, which has been removed (Fate #317016).

Chapter 4, Installation on IBM z Systems
Chapter 6, Installation with YaST
Chapter 13, Installing or Removing Software
Chapter 14, Installing Modules, Extensions, and Third Party Add-On Products
  • Updated chapter to reflect the software changes to the former YaST SUSE Customer Center Configuration dialog (now called Product Registration) and the YaST Add-On Products module (Fate #318800).

Chapter 12, Advanced Disk Setup
  • Mentioned that subvolumes for /var/lib/mariadb, /var/lib/pgsql, and /var/lib/libvirt/images are created with the option no copy on write by default to avoid extensive fragmenting with Btrfs.

Subscription Management
Part VI, “Updating and Upgrading SUSE Linux Enterprise”
Bugfixes

A.7 February 2015 (Documentation Maintenance Update)

Section 6.12, “Clock and Time Zone”

With NTP disabled it is recommended to avoid writing system time to the hardware clock. Thus set SYSTOHC=no.

Bugfixes

A.8 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)

General
  • Removed all KDE documentation and references because KDE is no longer shipped.

  • Removed all references to SuSEconfig, which is no longer supported (Fate #100011).

  • Move from System V init to systemd (Fate #310421). Updated affected parts of the documentation.

  • YaST Runlevel Editor has changed to Services Manager (Fate #312568). Updated affected parts of the documentation.

  • Removed all references to ISDN support, as ISDN support has been removed (Fate #314594).

  • Removed all references to the YaST DSL module as it is no longer shipped (Fate #316264).

  • Removed all references to the YaST Modem module as it is no longer shipped (Fate #316264).

  • Btrfs has become the default file system for the root partition (Fate #315901). Updated affected parts of the documentation.

  • The dmesg now provides human-readable time stamps in ctime()-like format (Fate #316056). Updated affected parts of the documentation.

  • syslog and syslog-ng have been replaced by rsyslog (Fate #316175). Updated affected parts of the documentation.

  • MariaDB is now shipped as the relational database instead of MySQL (Fate #313595). Updated affected parts of the documentation.

  • SUSE-related products are no longer available from http://download.novell.com but from http://download.suse.com. Adjusted links accordingly.

  • Novell Customer Center has been replaced with SUSE Customer Center. Updated affected parts of the documentation.

  • /var/run is mounted as tmpfs (Fate #303793). Updated affected parts of the documentation.

  • The following architectures are no longer supported: IA64 and x86. Updated affected parts of the documentation.

  • The traditional method for setting up the network with ifconfig has been replaced by wicked. Updated affected parts of the documentation.

  • A lot of networking commands are deprecated and have been replaced by newer commands (usually ip). Updated affected parts of the documentation.

    arp: ip neighbor
    ifconfig: ip addr, ip link
    iptunnel: ip tunnel
    iwconfig: iw
    nameif: ip link, ifrename
    netstat: ss, ip route, ip -s link, ip maddr
    route: ip route
  • Numerous small fixes and additions to the documentation, based on technical feedback.

Chapter 2, Installation on AMD64 and Intel 64
  • Updated system requirements.

Chapter 3, Installation on IBM POWER
  • Added POWER8 to the list of supported hardware (Fate #315272).

  • SUSE Linux Enterprise Server 12 for POWER has moved to Little Endian. Updated affected parts of the documentation.

Chapter 4, Installation on IBM z Systems
  • Updated the list of supported platforms: Removed IBM Series z9 and z10 machines and added IBM zEnterprise BC12.

  • Updated the memory and disk space requirements.

  • Removed instructions on how to IPL from tape—this is no longer supported.

  • Rewrote large parts of Section 4.2.5, “Network Configuration” to remove redundant information and make it more concise.

  • Removed references to Token Ring, which is no longer supported (Fate #313154).

Chapter 6, Installation with YaST
Chapter 19, Upgrading SUSE Linux Enterprise
Chapter 11, Setting Up Hardware Components with YaST
Chapter 13, Installing or Removing Software
Chapter 14, Installing Modules, Extensions, and Third Party Add-On Products
Subscription Management
  • For registering clients against an SMT server, suse_register has been replaced with SUSEConnect (Fate #316585).

Bugfixes
SUSE Linux Enterprise Server 12 SP3

GNOME User Guide

Introduces the GNOME desktop of SUSE Linux Enterprise Server. It guides you through using and configuring the desktop and helps you perform key tasks. It is intended mainly for end users who want to make efficient use of GNOME as their default desktop.

Publication Date: April 04, 2018
About This Guide
Available Documentation
Feedback
Documentation Conventions
I Introduction
1 Getting Started with the GNOME Desktop
1.1 Logging In
1.2 Desktop Basics
1.3 Pausing or Finishing Your Session
2 Working with Your Desktop
2.1 Managing Files and Directories
2.2 Accessing Removable Media
2.3 Searching for Files
2.4 Copying Text Between Applications
2.5 Managing Internet Connections
2.6 Exploring the Internet
2.7 E-mail and Scheduling
2.8 Opening or Creating Documents with LibreOffice
2.9 Controlling Your Desktop’s Power Management
2.10 Creating, Displaying, and Decompressing Archives
2.11 Taking Screenshots
2.12 Viewing PDF Files
2.13 Obtaining Software Updates
2.14 For More Information
3 Customizing Your Settings
3.1 The GNOME Settings Dialog
3.2 Personal
3.3 Hardware
3.4 System
4 Assistive Technologies
4.1 Enabling Assistive Technologies
4.2 Visual Impairments
4.3 Hearing Impairments
4.4 Mobility Impairments
4.5 For More Information
II Connectivity, Files and Resources
5 Accessing Network Resources
5.1 Connecting to a Network
5.2 General Notes on File Sharing and Network Browsing
5.3 Accessing Network Shares
5.4 Sharing Directories
5.5 Managing Windows Files
5.6 Configuring and Accessing a Windows Network Printer
6 Managing Printers
6.1 Installing a Printer
7 Backing Up User Data
7.1 Creating Backups
7.2 Restoring Data
8 Passwords and Keys: Signing and Encrypting Data
8.1 Signing and Encryption
8.2 Generating a New Key Pair
8.3 Modifying Key Properties
8.4 Importing Keys
8.5 Exporting Keys
8.6 Signing a Key
8.7 Password Keyrings
8.8 Key Servers
8.9 Key Sharing
9 gFTP: Transferring Data from the Internet
9.1 ASCII Compared to Binary Transfers
9.2 Connecting to a Remote Server
9.3 Transferring Files
9.4 Setting Up an HTTP Proxy Server
9.5 For More Information
III LibreOffice
10 LibreOffice: The Office Suite
10.1 LibreOffice Modules
10.2 Starting LibreOffice
10.3 The LibreOffice User Interface
10.4 Compatibility with Other Office Applications
10.5 Saving Files with a Password
10.6 Customizing LibreOffice
10.7 Changing the Global Settings
10.8 Using Templates
10.9 Setting Metadata and Properties
10.10 For More Information
11 LibreOffice Writer
11.1 Creating a New Document
11.2 Formatting with Styles
11.3 Working with Large Documents
11.4 Using Writer as an HTML Editor
12 LibreOffice Calc
12.1 Creating a New Document
12.2 Using Formatting and Styles in Calc
12.3 Working With Sheets
12.4 Conditional Formatting
12.5 Grouping and Ungrouping Cells
12.6 Freezing Rows or Columns as Headers
13 LibreOffice Impress, Base, Draw, and Math
13.1 Using Presentations with Impress
13.2 Using Databases with Base
13.3 Creating Graphics with Draw
13.4 Creating Mathematical Formulas with Math
IV Internet, Communication and Collaboration
14 Firefox: Browsing the Web
14.1 Starting Firefox
14.2 Navigating Web Sites
14.3 Finding Information
14.4 Managing Bookmarks
14.5 Using the Download Manager
14.6 Security
14.7 Customizing Firefox
14.8 Printing from Firefox
14.9 For More Information
15 Evolution: E-Mailing and Calendaring
15.1 Starting Evolution
15.2 Setup Assistant
15.3 Using Evolution
15.4 For More Information
16 Empathy: Instant Messaging
16.1 Starting Empathy
16.2 Configuring Accounts
16.3 Managing Contacts
16.4 Chatting with Friends
16.5 For More Information
17 Ekiga: Using Voice over IP
17.1 Starting Ekiga
17.2 Configuring Ekiga
17.3 The Ekiga User Interface
17.4 Making a Call
17.5 Answering a Call
17.6 Using the Address Book
17.7 For More Information
V Graphics and Multimedia
18 GIMP: Manipulating Graphics
18.1 Graphics Formats
18.2 Starting GIMP
18.3 User Interface Overview
18.4 Getting Started
18.5 Saving and Exporting Images
18.6 Editing Images
18.7 Printing Images
18.8 For More Information
19 GNOME Videos
19.1 Using GNOME Videos
19.2 Modifying GNOME Videos Preferences
20 Brasero: Burning CDs and DVDs
20.1 Creating a Data CD or DVD
20.2 Creating an Audio CD
20.3 Copying a CD or DVD
20.4 Writing ISO Images
20.5 Creating a Multisession CD or DVD
20.6 For More Information
A Help and Documentation
A.1 Using GNOME Help
A.2 Additional Help Resources
A.3 For More Information
B Documentation Updates
B.1 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)
B.2 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)
B.3 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)
B.4 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)
C GNU Licenses
C.1 GNU Free Documentation License
List of Examples
11.1 Use of Styles

Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

About This Guide

  • Filename: gnomeuser_intro.xml
  • ID: pre.gnome.about

This manual introduces you to the GNOME graphical desktop environment as implemented in SUSE® Linux Enterprise Server, and shows you how to configure it to meet your personal needs and preferences. It also introduces you to several programs and services. It is intended for users who have experience using a graphical desktop environment such as macOS*, Windows*, or other Linux desktops.

The manual is divided into the following parts:

Introduction

Get to know your GNOME desktop, learn how to cope with basic and daily tasks using the central GNOME applications and various small utilities. Get an overview of the possibilities that GNOME offers for modifying and individualizing the desktop according to your needs and wishes. Learn how to use assistive technologies to improve accessibility in case of vision or mobility impairment.

Connectivity, Files and Resources

Learn how to manage and exchange data on your system or on a network: connecting to a network and sharing files, managing printers, or creating backups of your data. This part also shows how to sign and encrypt your mails and documents and how to use file transfer clients to transfer data from or to the Internet.

LibreOffice

Introduces the LibreOffice suite, including Writer, Calc, Impress, Base, Draw, and Math.

Internet, Communication and Collaboration

Use a Web browser and get to know the e-mailing and calendaring software. Communicate with others using Instant Messaging or Voice over IP.

Graphics and Multimedia

Get to know GIMP, an image manipulation program that meets the needs of both amateurs and professionals. Get introduced to your desktop's applications for playing movies. Learn how to create data or audio CDs and DVDs for archiving your data.

1 Available Documentation

  • Filename: common_intro_available_doc_i.xml
  • ID: no ID found
Note
Note: Online Documentation and Latest Updates

Documentation for our products is available at http://www.suse.com/documentation/, where you can also find the latest updates, and browse or download the documentation in various formats.

In addition, the product documentation is usually available in your installed system under /usr/share/doc/manual.

The following documentation is available for this product:

Installation Quick Start

Lists the system requirements and guides you step-by-step through the installation of SUSE Linux Enterprise Server from DVD, or from an ISO image.

Deployment Guide

Shows how to install single or multiple systems and how to exploit the product inherent capabilities for a deployment infrastructure. Choose from various approaches, ranging from a local installation or a network installation server to a mass deployment using a remote-controlled, highly-customized, and automated installation technique.

Administration Guide

Covers system administration tasks like maintaining, monitoring and customizing an initially installed system.

Virtualization Guide

Describes virtualization technology in general, and introduces libvirt—the unified interface to virtualization—and detailed information on specific hypervisors.

Storage Administration Guide

Provides information about how to manage storage devices on a SUSE Linux Enterprise Server.

AutoYaST

AutoYaST is a system for unattended mass deployment SUSE Linux Enterprise Server systems using an AutoYaST profile containing installation and configuration data. The manual guides you through the basic steps of auto-installation: preparation, installation, and configuration.

Security Guide

Introduces basic concepts of system security, covering both local and network security aspects. Shows how to use the product inherent security software like AppArmor or the auditing system that reliably collects information about any security-relevant events.

Security and Hardening Guide

Deals with the particulars of installing and setting up a secure SUSE Linux Enterprise Server, and additional post-installation processes required to further secure and harden that installation. Supports the administrator with security-related choices and decisions.

System Analysis and Tuning Guide

An administrator's guide for problem detection, resolution and optimization. Find how to inspect and optimize your system by means of monitoring tools and how to efficiently manage resources. Also contains an overview of common problems and solutions and of additional help and documentation resources.

SMT Guide

An administrator's guide to Subscription Management Tool—a proxy system for SUSE Customer Center with repository and registration targets. Learn how to install and configure a local SMT server, mirror and manage repositories, manage client machines, and configure clients to use SMT.

GNOME User Guide

Introduces the GNOME desktop of SUSE Linux Enterprise Server. It guides you through using and configuring the desktop and helps you perform key tasks. It is intended mainly for end users who want to make efficient use of GNOME as their default desktop.

2 Feedback

  • Filename: common_intro_feedback_i.xml
  • ID: no ID found

Several feedback channels are available:

Bugs and Enhancement Requests

For services and support options available for your product, refer to http://www.suse.com/support/.

Help for openSUSE is provided by the community. Refer to https://en.opensuse.org/Portal:Support for more information.

To report bugs for a product component, go to https://scc.suse.com/support/requests, log in, and click Create New.

User Comments

We want to hear your comments about and suggestions for this manual and the other documentation included with this product. Use the User Comments feature at the bottom of each page in the online documentation or go to http://www.suse.com/documentation/feedback.html and enter your comments there.

Mail

For feedback on the documentation of this product, you can also send a mail to doc-team@suse.com. Make sure to include the document title, the product version and the publication date of the documentation. To report errors or suggest enhancements, provide a concise description of the problem and refer to the respective section number and page (or URL).

3 Documentation Conventions

  • Filename: common_intro_typografie_i.xml
  • ID: no ID found

The following notices and typographical conventions are used in this documentation:

  • /etc/passwd: directory names and file names

  • PLACEHOLDER: replace PLACEHOLDER with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • package name : name of a package

  • Alt, AltF1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File › Save As: menu items, buttons

  • x86_64 This paragraph is only relevant for the AMD64/Intel 64 architecture. The arrows mark the beginning and the end of the text block.

    System z, POWER This paragraph is only relevant for the architectures z Systems and POWER. The arrows mark the beginning and the end of the text block.

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

  • Commands that must be run with root privileges. Often you can also prefix these commands with the sudo command to run them as non-privileged user.

    root # command
    tux > sudo command
  • Commands that can be run by non-privileged users.

    tux > command
  • Notices

    Warning
    Warning: Warning Notice

    Vital information you must be aware of before proceeding. Warns you about security issues, potential loss of data, damage to hardware, or physical hazards.

    Important
    Important: Important Notice

    Important information you should be aware of before proceeding.

    Note
    Note: Note Notice

    Additional information, for example about differences in software versions.

    Tip
    Tip: Tip Notice

    Helpful information, like a guideline or a piece of practical advice.

Part I Introduction

1 Getting Started with the GNOME Desktop

This section describes the conventions, layout, and common tasks of the GNOME desktop as implemented in your product.

2 Working with Your Desktop

In this chapter you will learn how to work with files and burn CDs. You will also find out how to perform regular tasks with your desktop.

3 Customizing Your Settings

You can change the way the GNOME desktop looks and behaves to suit your own personal tastes and needs. Some possible changes of settings are:

4 Assistive Technologies

The GNOME desktop includes assistive technologies to support users with various impairments and special needs, and to interact with common assistive devices. This chapter describes several assistive technology applications designed to meet the needs of users with physical disabilities like low vision or impaired motor skills.

1 Getting Started with the GNOME Desktop

  • Filename: gnome_start.xml
  • ID: cha.gnomeuser.start

This section describes the conventions, layout, and common tasks of the GNOME desktop as implemented in your product.

GNOME is an easy-to-use graphical interface that can be customized to meet your needs and personal preferences. This section describes the default configuration of GNOME. If you or your system administrator modify the defaults, some aspects might be different, such as appearance or key combinations.

Note
Note: Included Session Configurations

Some versions of SUSE Linux Enterprise ship with as many as three different session configurations based on GNOME. These are GNOME, GNOME Classic, and SLE Classic. The version described here is the default configuration of SUSE Linux Enterprise Desktop called SLE Classic.

1.1 Logging In

In general, all users must authenticate—unless Auto Login is enabled for a specific user. In this case, a particular user will be logged in automatically when the system starts. This can save some time, especially if a computer is used by a single person. It may impact account security. Auto Login can be enabled or disabled during installation or at any time using the YaST User and Group Management module. For more information, refer to Chapter 16, Managing Users with YaST.

If your computer is running in a network environment and you are not the only person using the machine, you are usually prompted to enter your user name and password when you start the system.

GNOME Login Screen
Figure 1.1: GNOME Login Screen
Procedure 1.1: Normal Login
  1. If your user name is listed, click it.

    If your user name is not listed, click Not listed?. Then enter your user name and click Next.

  2. Enter your password and click Sign in.

1.1.1 Switching the Session Type Before Logging In

If you want to try one of the additional GNOME session configurations or try another desktop environment, follow the steps below.

  1. On the login screen, click your user name or enter it, as you normally would.

  2. To change the session type, click the cog wheel icon. A menu appears.

    GNOME Login Screen—Session Type
    Figure 1.2: GNOME Login Screen—Session Type
  3. From the menu, select one of the entries. Depending on your configuration there may be different choices, but the default selection is as follows.

    GNOME

    A GNOME 3 configuration that is very close to the upstream design. It focuses on interrupting users as little as possible. However, starting applications and switching between them works differently from many other desktop operating systems. It uses a single panel at the top of the screen.

    GNOME Classic

    A GNOME 3 configuration that is designed to appeal to former users of GNOME 2. The desktop has two panels, one at the top and another at the bottom.

    IceWM

    A very basic desktop designed to use little resources. It can be used as a fallback, if other options do not work or are slow.

    SLE Classic (default)

    The default desktop of SUSE Linux Enterprise, designed to appeal to users of older versions of SUSE Linux Enterprise and users of Microsoft* Windows*. This desktop is a GNOME 3 configuration and uses a single panel that is placed at the bottom of the screen.

  4. Enter your password into the text box, then click Sign In.

After switching to another session type once, the chosen session will become your default session. To switch back, repeat the steps above.

1.1.2 Assistive Tools

In the top right corner, there are status icons and the assistive technologies menu. By clicking the status icons, open a menu that allows you to set the sound volume and restart or power off the machine.

1.2 Desktop Basics

The GNOME desktop appears after you first log in. It displays a panel at the bottom showing the following elements (from left to right):

Applications menu

Click Applications in the left corner to open a menu with all the installed programs. These are classified under different categories for a better overview. Sub-items open automatically when you place the mouse above them.

Click Activities Overview in the bottom part of the Applications menu to open Activities Overview where you can start programs and manage those already running.

The Activity Overview is described further in Section 1.2.1, “Activities Overview”.

Places menu

Click Places to open a menu with shortcuts to your personal directories, connected storage media, and network resources.

Task switcher

All applications currently open on the desktop (on the active workspace) appear in the middle part of the panel. You can bring these applications to the foreground by clicking their names.

Notification indicator (not always visible)

When there are notifications, for example, for new chat or e-mail messages or concerning system updates, an indicator will appear. The indicator is a blue circle with the number of available notifications displayed in the middle. Click the indicator to open the Message Tray where you can interact with all the notifications.

Workspace switcher

This menu lets you select a workspace (also called a virtual desktop) to work on. This feature can help you work with many windows. For example, you could move windows needed for one project to workspace 1 and windows needed for another project to workspace 2.

Date and time

The current day of the week and time are shown to the right from the workspace switcher. Click it to open a menu where you can access a calendar and adjust date and time settings.

Status icons

In the right corner of the panel, icons showing the current status of the network connection, sound volume and power/battery status are displayed.

Click the icons to open a menu where you can adjust sound volume, display brightness, network connection, and power settings. Click the name to display the options for logging out or for switching to another user.

The three icons in the lower part of the menu allow you to, from left to right, open the GNOME settings dialog, lock the screen, and power off or restart your computer.

GNOME Desktop—SLE Classic
Figure 1.3: GNOME Desktop—SLE Classic

1.2.1 Activities Overview

Activities Overview is a full screen mode that comprises all the ways in which you can switch from one activity to another. It shows previews of all open windows and icons for favorite and running applications. It also integrates searching and browsing functionality.

1.2.1.1 Opening the Activities Overview

There are multiple ways to open the Activities Overview:

  • Open the Applications menu on the bottom panel and select Activities Overview.

  • Press Meta.

  • Forcefully move the pointer to the top left corner (the so-called hot corner).

1.2.1.2 Using the Activities Overview

In the following, the most important parts of the Activities Overview are explained.

Dash

The Dash is the bar positioned on the center left. It contains favorite applications and all applications with open windows. If you move the mouse pointer over one of the icons, GNOME will display the name of the corresponding application nearby. A light glow indicates that the application is running and has at least one open window.

Right-clicking an icon opens a menu which offers different actions depending on the associated program. Using Add to Favorites, you can place the application icon permanently in Dash. To remove a program icon from Dash, select Remove from Favorites. To rearrange an icon, use the mouse to drag it to a new position.

Search box

On the top, there is a search box that you can use to find applications, settings and files in your home directory.

To search, you do not need to click the search box. You can begin typing directly after opening Activity Overview. Search starts immediately, you do not need to press Enter.

Workspace selector

On the right, there is an overview of available workspaces. To switch to the selected desktop, click the preview of it.

To move a window from one workspace to another, drag a window preview from one workspace preview to another.

1.2.2 Starting Programs

To start a program, you have several options:

  • In the bottom panel, click Applications and select the desired program from the hierarchical menu.

  • Open the Activities Overview by pressing Meta. Now click an application icon or search for an application. If you do not know the exact application name, you can search for generic category names such as image editor.

    Further information about the activities overview can be found in Section 1.2.1, “Activities Overview”.

  • If you know the exact command to start the program, you can press AltF2, enter the command into the dialog and press Enter.

    Note that the only button displayed in the window is labeled Close and will indeed close the window.

1.3 Pausing or Finishing Your Session

When you have finished using the computer, there are multiple ways to finish the session. Which one is right in a given situation depends on how long you will be away and whether you are worried about energy consumption, among other things.

  • Locking the Computer.  Pause your session, but keep the computer on. Make sure that nobody can look at or change your work while you are away on a break. Other users can log in and work in the meantime. Other users can shut down the computer, but a prompt will warn them that you are still logged in.

  • Logging Out.  Finish the current session, but leave the computer on, so other users can log in.

  • Shutting Down.  Finish the current session and turn off the computer.

  • Restarting.  Finish the current session and restart the computer. Restarting is necessary to apply some system updates.

  • Suspending the Computer.  Pause your session and put the computer in a state where it consumes a minimal amount of energy. Suspend mode can be configured to lock your screen, so nobody can look at or change your work. Waking up the computer is generally much quicker than a full computer start.

    This mode is also known as suspend-to-RAM, sleep or standby mode.

1.3.1 Locking the Screen

To lock the screen, click the status icons on the right of the main panel and click the padlock icon.

When you lock your screen, at first a curtain with a clock will appear. After some time the screen turns black. To unlock the screen, move the mouse or press a key to display the locked screen dialog. Enter your password, then press Enter to unlock the screen.

1.3.2 Logging Out or Switching Users

  1. Click the status icons on the right of the main panel to open the menu.

  2. Click your user name.

  3. Select one of the following options:

    Log Out

    Logs you out of the current session and returns you to the Login screen.

    Switch User

    Suspends your session, allowing another user to log in and use the computer.

    Account Settings

    Takes you to the user settings where you can change your password.

1.3.3 Restarting or Shutting Down the Computer

  1. Click the status icons on the right of the main panel to open the menu.

  2. Click the power off icon in the lower right part of the menu.

  3. Select one of the following options:

    Power Off

    Logs you out of the current session, then turns off the computer.

    Restart

    Logs you out of the current session, then restarts the computer.

1.3.4 Suspending the Computer

  1. Click the status icons on the right of the main panel to open the menu.

  2. Hold Alt pressed. The power off icon in the lower right part of the menu turns into a pause icon. Click the pause icon.

2 Working with Your Desktop

  • Filename: gnome_use.xml
  • ID: cha.gnomeuser.use

In this chapter you will learn how to work with files and burn CDs. You will also find out how to perform regular tasks with your desktop.

2.1 Managing Files and Directories

You can open GNOME Files in multiple ways:

  • Click Applications › Accessories › Files.

  • Open the Activities Overview and search for files.

  • On the desktop, double-click Home.

  • Open the Places menu and select any entry, such as Home.

File Manager
Figure 2.1: File Manager

The elements of the GNOME Files window include the following:

Toolbar

The toolbar contains back and forward buttons, the path bar, a search function, elements to let you change the layout of the content area, and the application menu.

Menu

The menu is the last icon on the toolbar. It lets you perform many tasks, such as opening the preferences dialog, creating a new directory or opening a new window or tab.

Sidebar

The sidebar lets you navigate between often-used directories and external or network storage devices. To display or hide the sidebar, press F9.

Content Area

Displays files and directories.

Use the icons in the top right part of the window to switch between list and grid icon view.

Context Menus

Open a context menu by right-clicking inside the content area. The items in this menu depend on where you right-click.

For example, if you right-click a file or directory, you can select items related to the file or directory. If you right-click the background of a content area, you can select items related to the display of items in the content area.

Floating Statusbar

The floating statusbar appears when a file is selected. It displays the file name and size.

2.1.1 Key Combinations

The following table lists a selection of key combinations of GNOME Files.

Table 2.1: GNOME Files Key Combinations

Key Combination

Description

Alt/ Alt

Go backward/go forward.

Alt

Open the parent directory.

, , ,

Select an item.

Alt or Enter

Open an item.

AltEnter

Open an item's Properties dialog.

ShiftAlt

Open an item and close the current directory.

CtrlL

Transform the path bar from a button view to a text box.

Exit this mode by pressing Enter (go to the location) or Esc (to remain in the current directory).

/

Transform the path bar from a button view to a text box and replace the current path with /.

AltHome

Open your home directory.

Any number or letter key

Start a search within the current directories and their subdirectories. The character you pressed is used as the first character of the search term. Search happens as you type, you do not need to press Enter.

CtrlT

Start a search within the current directories and their subdirectories. The character you pressed is used as the first character of the search term. Search happens as you type, you do not need to press Enter.

Del

Moves the selected file or directory to the trash, from which it can be restored with Undo.

2.1.2 Compressing Files or Directories

Sometimes, it is useful to archive or compress files, for example:

  • You want to attach an entire directory, including its subdirectories, to an e-mail.

  • You want to attach a large file to an e-mail.

  • You want to save space on your hard disk and have files you rarely use.

In all these cases, you can create a compressed file, such as a ZIP file, which can contain multiple original files. How much smaller the compressed version is than the original depends on the file type. Many video, image and office document formats are already compressed and will only become marginally smaller.

  1. In the GNOME Files content area, right-click the directory you want to archive, then click Compress.

  2. Accept the default archive file name or provide a new one.

  3. Select a file extension from the drop-down box.

    • .zip files are supported on most operating systems, including Windows*.

    • .tar.gz files are compatible with most Linux* and Unix* systems.

    • .7z files usually offer better compression ratios than other formats, but are not as widely supported.

  4. Specify a location for the archive file, then click Create.

To extract an archived file, right-click the file, then select Extract Here. You can also double-click the compressed file to open it and see which files are included.

For more information on compressed files, see Section 2.10, “Creating, Displaying, and Decompressing Archives”.

2.1.3 Burning a CD/DVD

If your system has a CD or DVD writer, you can use GNOME Files to burn CDs and DVDs. If you want to burn an audio CD or need more control over the result, see Chapter 20, Brasero: Burning CDs and DVDs.

  1. Open GNOME Files.

  2. Insert a blank medium.

  3. Find the files you want to add to the medium and drag them to the sidebar item called Blank CD-R Disc. (The label may read slightly differently, depending on the type of medium you inserted.) When your mouse pointer is over the sidebar item, a small + should appear next to the pointer.

  4. When you have dragged all files onto the sidebar item Blank CD-R Disc, click it.

  5. Provide a name next to Disc Name or keep the proposal.

  6. Click Write to Disc.

  7. In the appearing dialog CD/DVD Creator, make sure the right medium is selected. Then click Burn.

    The files are burned to the disc. This can take a few minutes, depending on the amount of data being burned and the speed of your burner.

  8. After the medium has been burned, it will be ejected from the drive. In the window CD/DVD Creator, you can click Close.

To burn an ISO disc image, first insert a medium, then double-click the ISO file in GNOME Files. In the dialog Image Burning Setup, click Burn.

2.1.4 Creating a Bookmark

Use the bookmarks feature in GNOME Files to quickly jump to your favorite directories from the sidebar.

  1. Switch to the directory for which you want to create a bookmark in the content area.

  2. Click the list icon, then select Bookmark this Location from the menu.

    The bookmark now appears in the sidebar, with the directory name as the bookmark name.

  3. (Optional) If you want, you can change the name of the bookmark. This does not affect the name of the bookmarked directory itself. To change the name, right-click the new sidebar item and select Rename.

  4. (Optional) If you want, you can change the order in which the bookmarks are displayed. To reorder, click a bookmark and drag it to the desired location.

To switch to a bookmarked directory, click the appropriate sidebar item.

2.1.5 Accessing Remote Files

You can use GNOME Files to access files on remote servers. For more information, see Chapter 5, Accessing Network Resources.

2.2 Accessing Removable Media

To access CDs/DVDs or flash disks, insert or attach the medium. An icon for the medium is automatically created on the desktop. For many types of removable media, a GNOME Files window pops up automatically. If GNOME Files does not open, double-click the icon for that drive on the desktop to view the contents. In GNOME Files, you will see an item for the medium in the sidebar.

Warning
Warning: Unmount to Prevent Data Loss

Do not physically remove flash disks immediately after using them. Even when the system does not indicate that data is being written, the drive may not be finished with a previous operation.

In the sidebar of GNOME Files, click the Eject icon next to the medium to safely remove or unmount the drive.

2.3 Searching for Files

There are multiple ways to search for files or directories. In all cases, the search will be performed on file and directory names. Searching by file size, modification date and other properties is only partially possible in the preinstalled graphical tools. Such searches are easier to do on the command line.

Using GNOME Files

In GNOME Files, navigate to the directory from which you want to start the search. Then start typing the search term. To search for objects with a certain modification date or file type, click the arrow-down icon of the search box and modify the properties.

Using the Activities Overview

Open the Activities Overview by pressing Meta. Then start typing the search term. The search will be performed within your home directory.

Using the Desktop Search application

Click Applications › Accessories › Desktop Search. Enter the search term in the text box Search. The search will be performed within your home directory.

2.4 Copying Text Between Applications

Copy and paste works the same as in other operating systems. First select the text, so that it appears highlighted, usually in blue. Then press CtrlC. Now move the keyboard focus to the right position. Finally, to insert the text, press CtrlV.

To copy or paste in the terminal, additionally press Shift together with the above key combinations.

An alternative way of using copy and paste is described in the following. First select the text. To paste the text, middle-click over the position where you want the text to be pasted. As soon as you make another selection, the text from the original selection will be replaced in the clipboard.

When copying information between programs, you must keep the source program open and paste the text before closing it. When a program closes, any content from that application that is on the clipboard is lost.

2.5 Managing Internet Connections

To surf the Web or send and receive e-mail messages, you must have configured an Internet connection. If you have installed SUSE Linux Enterprise Server on a laptop or a mobile device, NetworkManager is enabled by default. On the GNOME desktop, you can then establish Internet connections with NetworkManager as described in Section 36.3, “Configuring Network Connections”.

Depending on your environment, you can choose in YaST which basic service to use for setting up network connections (either NetworkManager or wicked). For details, see Section 16.4.1.1, “Configuring Global Networking Options”.

2.6 Exploring the Internet

The GNOME desktop includes Firefox, a Mozilla*-based Web browser. You can start it by clicking Applications › Internet › Firefox.

You can type an address into the location bar at the top or click links in a page to move to different pages, like in any other Web browser.

For more information, see Chapter 14, Firefox: Browsing the Web.

2.7 E-mail and Scheduling

For reading and managing your mail and events, use Evolution. Evolution is a groupware program that makes it easy to store, organize and retrieve your personal information.

Evolution seamlessly combines e-mail, a calendar, an address book, and a memo and task list in one easy-to-use application. With its extensive support for communications and data interchange standards, Evolution can work with existing corporate networks and applications, including Microsoft* Exchange.

To start Evolution, click Applications › Internet › Evolution.

The first time you start Evolution, it prompts you with a few questions to set up a mail account and import mail from an old mail client. Then it shows you how many new messages you have and lists upcoming appointments and tasks. The calendar, address book and mail tools are available in the shortcut bar on the left.

For more information, see Chapter 15, Evolution: E-Mailing and Calendaring.

2.8 Opening or Creating Documents with LibreOffice

For creating and editing documents, LibreOffice is installed with the GNOME desktop. LibreOffice is a complete set of office tools that can both read and save Microsoft Office file formats. LibreOffice has a word processor, a spreadsheet, a database, a drawing tool and a presentation program.

To start LibreOffice, click Applications › Office › LibreOffice.

For more information, see Chapter 10, LibreOffice: The Office Suite.

2.9 Controlling Your Desktop’s Power Management

To see the state of the computer battery on your laptop, check the battery icon in the right part of the panel. On certain events, such as a critically low battery state, GNOME will display notifications informing you about the event.

You can open the power settings via Applications › System Tools › Settings › Power.

For more information, see Section 3.3.2, “Configuring Power Settings”.

2.10 Creating, Displaying, and Decompressing Archives

You can use the Archive Manager application (also known as File Roller) to create, view, modify or unpack an archive. An archive is a file that acts as a container for other files. An archive can contain many files, directories and subdirectories, usually in compressed form. Archive Manager supports common formats such as zip, tar.gz, tar.bz2, lzh, and rar. You can use Archive Manager to create, open and extract a compressed non-archive file.

To start Archive Manager, click Applications › Utilities › Archive Manager.

If you already have a compressed file, double-click the file name in GNOME Files to view the contents of the archive in Archive Manager.

Archive Manager
Figure 2.2: Archive Manager

2.10.1 Opening an Archive

  1. In Archive Manager, click Open.

  2. Select the archive you want to open.

  3. Click Open.

    Archive Manager displays the following:

    • The archive name in the titlebar.

    • The archive contents in the content area.

    To open another archive, click Open again. Archive Manager opens each archive in a new window. To open another archive in the same window, you must first select Close from the menu in the right part of the window to close the current archive, then click Open.

    If you try to open an archive that was created in a format that Archive Manager does not recognize, the application displays an error message.

  4. To display the archive's properties, click the last icon in the titlebar and select Properties. Details like name, location, type, last modification, number of files, size, and compression ratio are shown.

2.10.2 Extracting Files from an Archive

  1. In Archive Manager, select the files that you want to extract.

  2. Click Extract.

  3. Specify the directory where Archive Manager will extracts the files.

  4. Choose from the following extraction options:

    Option

    Description

    All files

    Extracts all files from the archive.

    Selected files

    Extracts the selected files from the archive.

    Files

    Extracts from the archive all files that match the specified pattern.

    Keep directory structure

    Reconstructs the directory structure when extracting the specified files.

    For example, you specify /tmp in the Filename text box and extract all files. The archive contains a subdirectory called doc. If you select the Keep directory structure option, Archive Manager extracts the contents of the subdirectory to /tmp/doc.

    If you do not select the Keep directory structure option, Archive Manager does not create any subdirectories. Instead, it extracts all files from the archive, including files from subdirectories, to /tmp.

    Do not overwrite newer files

    If not active, the Archive Manager overwrites any files in the destination directory that have the same name as the specified files.

    If you select this option, Archive Manager does not extract the specified file if an existing file with the same name already exists in the destination directory.

  5. Click Extract.

    To extract an archived file in a file manager window without opening Archive Manager, right-click the file and select Extract Here.

    The Extract operation extracts a copy of the specified files from the archive. The extracted files have the same permissions and modification date as the original files that were added to the archive.

    The Extract operation does not change the contents of the archive.

2.10.3 Creating Archives

  1. In Archive Manager, click the main menu icon in the top left part of the window and select New Archive.

  2. Specify the name and location of the new archive.

  3. Select an archive type from the drop-down box.

  4. Click Create.

    Archive Manager creates an empty archive, but does not yet write the archive to disk. Archive Manager writes a new archive to disk only when the archive contains at least one file. If you create a new archive and quit Archive Manager before you add any files to the archive, the archive will be deleted.

  5. Add files and directories to the new archive:

    1. Click Add Files and select the files or directories you want to add.

    2. Click Add.

      Archive Manager adds the files to the current directory in the archive.

You can also add files to an archive in a file manager window without opening Archive Manager. See Section 2.1.2, “Compressing Files or Directories” for more information.

2.11 Taking Screenshots

You can take a snapshot of your screen or of an individual application window by using the Take Screenshots utility. Start it by pressing Print to take a screenshot of the entire desktop or by pressing AltPrint to take a screenshot of the currently active window or dialog.

The screenshots are automatically saved to your ~/Pictures directory.

You can also use GIMP to take screenshots. (For more information on GIMP, see Chapter 18, GIMP: Manipulating Graphics). In GIMP, click File › Create › Screenshot, select an area, choose a delay and then click Snap.

2.12 Viewing PDF Files

Documents that need to be shared or printed across platforms can be saved as PDF (Portable Document Format) files. Document Viewer (also known as Evince) can open PDF files and many similar file types, such as XPS, DjVu, or TIFF.

Note
Note: Rare Display Issues

In rare cases, documents will not be displayed correctly in Document Viewer. This can happen, for example, with certain forms, animations or 3D images. In such cases, ask the authors of the file what viewer they recommend. However, in some cases the recommended viewer will not work on Linux.

Document Viewer
Figure 2.3: Document Viewer

To open Document Viewer, double-click a PDF file in a file manager window. Document Viewer will also open when you download a PDF file from a Web site. To open Document Viewer without a file, select Applications › Office › Document Viewer.

To view a PDF file in Document Viewer, click the cog wheel icon to open the menu and select Open. Now locate the desired PDF file and click Open.

Use the navigation icons at the top of the window or the thumbnails in the left panel to navigate through the document. If your PDF document provides bookmarks, you can access them in the left panel of the viewer.

2.13 Obtaining Software Updates

When you connect to the Internet, the updater applet automatically checks whether software updates for your system are available. When important updates are available, you will receive a notification on your desktop.

For detailed information on how to install software updates with the updater applet and how to configure it, refer to the chapter about installing and removing software in Section 13.5, “Keeping the System Up-to-date”.

2.14 For More Information

Along with the applications described in this chapter for getting started, you can use many other applications on GNOME. Find detailed information about these applications in the other parts of this manual.

To learn more about GNOME and GNOME applications, see http://www.gnome.org.

To report bugs or add feature requests, go to http://bugzilla.gnome.org.

3 Customizing Your Settings

  • Filename: gnome_custom.xml
  • ID: cha.gnome.settings

You can change the way the GNOME desktop looks and behaves to suit your own personal tastes and needs. Some possible changes of settings are:

These settings and others can be changed in the All Settings dialog.

3.1 The GNOME Settings Dialog

Whereas YaST is a desktop-independent system-wide tool to configure most aspects of your product installation, the settings dialog is a GNOME configuration tool. It focuses on look and feel, personal settings and preferences of your GNOME desktop.

To access the GNOME settings dialog, click Applications › System Tools › Settings. The dialog is divided into the following three categories:

Personal

From here, you can change the background of your desktop or of the lock screen, and configure language settings. For more information, see Section 3.2, “Personal”.

Hardware

Allows you to configure hardware components such as monitors, printers, mouses/touchpads, network adapters and sound devices. You can also change key combination settings and set up power-saving features. For more information, see Section 3.3, “Hardware”.

System

Lets you configure system settings such as date and time, whether to start software when inserting flash disks or whether you want to share your screen with others. You can also set up user accounts. If you want, you can also start YaST from this screen, though it is also available separately from within the menu. For more information, see Section 3.4, “System”.

GNOME Settings Dialog
Figure 3.1: GNOME Settings Dialog

To change some system-wide settings, the control center will prompt you for the root password and start YaST. This is mostly the case for administrator settings (including most of the hardware, the graphical user interface, Internet access, security settings, user administration, software installation and system updates and information). Follow the instructions in YaST to configure these settings. For information about using YaST, refer to the integrated YaST help texts or to the Deployment Guide.

This chapter focuses on individual settings you can change directly in the GNOME settings dialog, without having to use YaST.

3.2 Personal

The following sections introduce examples of how to configure some personal aspects of your GNOME desktop, like your languages used or desktop backgrounds.

3.2.1 Changing the Desktop Background

The desktop background is the image or color that is applied to your desktop. You can also customize the image shown when the screen is locked.

To change the desktop background or the lock screen:

  1. Click Applications › System Tools › Settings › Background.

  2. Click Background or Lock Screen.

  3. Click Wallpapers, Pictures, or Colors.

    Wallpapers are preconfigured images distributed with your system. Pictures are your own images from your Pictures directory (~/Pictures). Colors are predefined colors chosen by GNOME developers.

  4. Choose an option from the list.

  5. When you are satisfied with your choice, click Select.

3.2.2 Configuring Language Settings

SUSE Linux Enterprise Server can be configured to use any of several languages. The language setting determines the language of dialogs and menus and can also determine the keyboard and clock layout.

To configure your language settings click Applications › System Tools › Settings › Region and Language.

Here you can choose:

  • Interface language.

  • Date and number formats, currency and related options.

  • Input sources (keyboard layout). For non-alphabetic languages there can be additional settings.

Note
Note: Settings Made Using ibus-setup Do Not Take Effect

On GNOME, settings made using ibus-setup do not take effect. ibus-setup can only be used to configure IceWM. Instead, always use the Settings application:

  • To change input methods, use the panel Region & Language.

  • To change the key combination that switches between input methods, use the panel Keyboard. In it, choose the category Typing and the entry Switch to next input source.

3.3 Hardware

In the following sections you will find examples of how to configure some hardware aspects of your GNOME desktop, including keyboard or mouse preferences, handling of removable drives (and other media) or screen resolution.

3.3.1 Configuring Bluetooth Settings

The Bluetooth module lets you set the visibility of your machine over Bluetooth and connect to available Bluetooth devices. To configure Bluetooth connectivity, follow these steps:

  1. Click Applications › System Tools › Settings › Bluetooth to open the Bluetooth settings module.

  2. To use Bluetooth, turn the Bluetooth switch on.

  3. To make your computer visible over Bluetooth, turn the Visibility switch on. The computer will start searching for other visible Bluetooth devices in the vicinity and display any found devices in the Devices list. At first, the list may be empty.

    Note
    Note: Temporary Visibility

    The Visibility switch is meant to be used only temporarily. You only need to turn it on for the initial setup of a connection to a Bluetooth device. After the connection has been established, turn off the switch.

  4. On the device you want to connect, turn on Bluetooth connectivity and visibility, too.

  5. If the desired device has been found and is shown in the list, click it to establish a connection to it.

    You will be asked whether the PINs of the two devices match.

  6. If the PINs match, confirm this on both your computer and the device.

    Both are now paired. On your computer, the device in the list is shown as Connected.

    Depending on the device type, you can now either see it as a storage device in GNOME Files, set a volume for it in the Sound settings or other things.

To connect to a paired Bluetooth device, select the device in the list. In the dialog that appears, turn the Connection switch on. You can send files to the connected device by using the Send Files button. If you are connected to a device such as a mobile phone, you can use it as a network device by activating the appropriate option.

To remove a connected device from the list on your computer, click Remove Device and confirm your choice. To completely remove the pairing, you also need to do so on your device.

3.3.2 Configuring Power Settings

  1. Click Applications › System Tools › Settings › Power to open the Power settings module.

  2. In the upper part of the dialog, you can see the current state of the battery.

  3. In the Power Saving section of the dialog, set the Screen Brightness to conserve power. You can also set whether to dim the screen after a period of inactivity and set the time interval. You can also set whether to turn off wireless networking after the period of inactivity.

  4. In the Suspend and Power Button section of the dialog, set the Automatic Suspend. When you click it, a separate dialog opens.

    In it, you can turn on automatic suspending and associated time intervals. If you are using a computer with a battery, you can set these separately for computer running on battery power or plugged in.

    You can also set the action performed when the power button is pressed. Choose Hibernate to use a mode where the computer turns off completely but saves your running session to the hard disk. Alternatively, choose Suspend or Nothing.

3.3.3 Modifying Keyboard Shortcuts

To modify keyboard shortcuts click Applications › System Tools › Settings › Keyboard.

Keyboard Dialog
Figure 3.2: Keyboard Dialog

The Keyboard dialog shows the keyboard shortcuts that are configured for your system. Click the categories on the right to view the current shortcuts.

To edit a key combination, first click the row. To set a new key combination, press the keys. To disable a shortcut, press <— instead.

To configure keyboard accessibility options, refer to Section 4.4, “Mobility Impairments”. To configure your keyboard layout, refer to Section 3.2.2, “Configuring Language Settings”.

3.3.4 Configuring the Mouse and Touchpad

To modify mouse and touchpad options, click Applications › System Tools › Settings › Mouse and Touchpad.

Mouse and Touchpad Settings Dialog
Figure 3.3: Mouse and Touchpad Settings Dialog
  • In the General section of the dialog, you can set the Primary button orientation (left or right).

  • In the Mouse section of the dialog, use Mouse Speed to adjust the sensitivity of the mouse pointer.

  • In the Touchpad section of the dialog, you can turn the touchpad on and off. Use Touchpad Speed to adjust the sensitivity of the touchpad pointer. You can also disable the touchpad while typing and enable clicks by tapping the touchpad.

  • To test your settings, click Test Your Settings and try the pointing device.

For configuration of mouse accessibility options, refer to the Section 4.4, “Mobility Impairments”.

3.3.5 Installing and Configuring Printers

The Printers module lets you connect to any available local or remote CUPS server and configure printers.

To start the Printers module, click Applications › System Tools › Settings › Printers. For detailed information, refer to Chapter 6, Managing Printers.

3.3.6 Configuring Screens

To specify resolution and orientation for your screen or to configure multiple screens, click Applications › System Tools › Settings › Displays.

Procedure 3.1: Changing the Settings for a Monitor
  1. To find the right monitor, look for the numbers displayed in the upper left corner of all monitors after you have opened the Display dialog. To set options for a monitor, click the list item of the monitor. A new dialog appears.

  2. If multiple monitors are attached to the computer, the left part of the dialog will allow you to choose how to use the monitor. You can choose between:

    Primary

    The screen that shows the panel and important messages.

    Secondary Display

    A monitor that expands the desktop of the primary monitor.

    Mirror

    A monitor that mirrors the image on the primary monitor. In terms of resolution, the lowest common denominator will be used.

    Turn Off

    A screen that is not used.

    To rotate the displayed image, use the buttons with the arrows pointing left and right. To mirror the displayed image, use the button with the double arrow icon.

    You can set a different resolution by changing the value next to Resolution. Not all resolutions provide a sharp and unstretched image. To find the best resolution for your monitor, refer to its manual.

  3. When you are done, click Apply.

    The monitors will now readjust. This can take multiple seconds during which the screen can be black or distorted.

    Afterward, a confirmation dialog will appear.

  4. If the configuration looks correct, click Keep Changes.

    If the configuration is not what you hoped for, click Revert Settings or wait for 20 seconds. The changes will then be reverted.

Monitor Resolution Settings Dialog
Figure 3.4: Monitor Resolution Settings Dialog
Procedure 3.2: Changing the Arrangement of Multiple Monitors

If you are using multiple screens, set up how they are arranged, so you can use the mouse pointer properly across monitors.

  1. Click Arrange Combined Displays.

  2. To find the right monitor, look for the numbers displayed in the upper left corner of all monitors. Click and drag the monitor image around to move it.

  3. When you are done, click Apply.

  4. If the configuration looks correct, click Keep Changes.

    If the configuration is not what you hoped for, click Revert Settings or wait for 20 seconds. The changes will then be reverted.

3.3.7 Configuring Sound Settings

The Sound tool lets you manage sound devices and set the sound effects. In the top part of the dialog, you can select the general output volume or turn the sound off completely.

To open the sound settings, click Applications › System Tools › Settings › Sound.

Configuring Sound Settings
Figure 3.5: Configuring Sound Settings

3.3.7.1 Configuring Sound Devices

Use the Output tab to select the device for sound output. Below the list, choose the sound device setting you prefer, for example balance.

Use the Input tab to set the input device volume or to mute the input temporarily. If you have more than one sound device, you can also select a default device for audio input in the Choose a device for sound input list.

3.3.7.2 Configuring Sound Effects

Use the Sound Effects tab to configure whether and how you want sound to be played when message boxes appear.

Specify the volume at which the sound effects will be played under Alert volume. You can also turn the effects on and off.

Select the Alert Sound to use.

3.3.8 Networking

To set up networking options, click Applications › System Tools › Settings › Network.

In the appearing dialog, you can configure wired or wireless connections and proxies and VPNs.

To learn more about setting up network connections, see Chapter 36, Using NetworkManager.

3.4 System

In the following sections, you will find examples of how to configure some system aspects of your GNOME desktop. These include preferred applications, changing your user password, and session sharing preferences.

To learn more about configuring assistive technologies, see Chapter 4, Assistive Technologies.

3.4.1 Changing Your Password

For security reasons, it is a good idea to change your login password from time to time. To change your password:

  1. Click Applications › System Tools › Settings › Users.

  2. Click the button labeled with dots next to Password.

  3. In the first text box, type your current password.

  4. In the next text box, type a new password.

    You can also click the cog wheel icon at the end of the text box to generate a random password.

  5. Confirm your new password by typing it again in the last text box.

  6. Click Change.

3.4.2 Setting Preferred Applications

  1. To change the default application for various common tasks such as browsing the Internet, sending mails or playing multimedia files, click Applications › System Tools › Settings › Details.

    Preferred Applications
    Figure 3.6: Preferred Applications
  2. Click Default Applications.

  3. Select one of the available applications from the drop-down box. You can choose an application to handle Web, mail, calendar, music, videos or photographs.

3.4.3 Setting Session Sharing Preferences

To open a configuration dialog for sharing a GNOME desktop session between multiple users and set session-sharing preferences, click Applications › System Tools › Settings › Sharing.

Important
Important: Sharing Desktop Sessions Affects System Security

Sharing desktop sessions can be a security risk. Use the restriction options available.

Before you can share anything, you need to turn on the switch in the upper part of the dialog. The switch also helps you if you quickly need to disable all sharing options.

  • To share your public directory over the network, click Personal File Sharing and turn on Share Public Folder On This Network. You can also set a password.

  • To share your desktop session with other users, click Screen Sharing and activate Allow Remote Control. To allow other users to control your screen, activate also Remote Control. You can also set a password.

  • To enable logging in via SSH, click Remote Login.

All the sharing screens contain an address which you can give to other users, so they can reach you. To copy a sharing address, click it and select Copy. You can then paste it into an e-mail or messaging software.

3.4.4 Configuring Administrative Settings with YaST

For your convenience, YaST is available from the GNOME Settings as well as from the Applications menu. For information about using YaST, refer to Deployment Guide.

4 Assistive Technologies

  • Filename: gnome_accessibility.xml
  • ID: cha.gnome.accessibility
Abstract

The GNOME desktop includes assistive technologies to support users with various impairments and special needs, and to interact with common assistive devices. This chapter describes several assistive technology applications designed to meet the needs of users with physical disabilities like low vision or impaired motor skills.

4.1 Enabling Assistive Technologies

To configure accessibility features, open the GNOME Settings dialog (for example using Applications › System Tools › Settings) and click Universal Access. Each assistive feature can be enabled separately using this dialog.

If you need a more direct access to individual assistive features, turn on Always Show Universal Access Menu in the Universal Access dialog. A new menu will appear on the bottom panel.

4.2 Visual Impairments

In the Seeing section of the Universal Access dialog, you can enable features that help people with impaired vision.

  • Turning on High Contrast enables high contrast black and white icons in the GNOME desktop.

  • Turning on Large Text enlarges the font used in the user interface.

  • Turning on Zoom enables a screen magnifier. You can set the desired magnification and magnifier behavior, including color effects.

  • If the Screen Reader is turned on, any UI element or text that receives keyboard focus is read aloud.

  • If the Sound Keys are turned on, a sound is played whenever Num Lock or Caps Lock are turned on.

4.3 Hearing Impairments

In the Hearing section of the Universal Access dialog, you can enable features helping people with impaired hearing.

If the Visual Alerts are turned on, a window title or the entire screen is flashed when an alert sound occurs.

4.4 Mobility Impairments

In the Typing and Pointing and Clicking sections of the Universal Access dialog, you can enable features that help people with mobility impairments.

  • If the Screen Keyboard is turned on, a virtual keyboard appears whenever you need to enter text. You can use the screen keyboard by clicking the virtual keys.

  • Click Typing Assist (AccessX) to open a dialog where you can enable various features that make typing easier.

    • With Enable by Keyboard, you can turn accessibility features on or off by using the keyboard.

    • Sticky Keys allows you to type key combinations one key at a time rather than having to hold down all of the keys at once. For example, the Alt→| shortcut switches between windows.

      With sticky keys turned off, you need to hold down both keys at the same time. With sticky keys turned on, press Alt and then →| to do the same.

    • Turn on Slow Keys if you want a delay between pressing a key and the letter being displayed on the screen. This means that you need to hold down each key you want to type for a little while before it appears. Use slow keys if you accidentally press several keys at a time when you type, or if you find it difficult to press the right key on the keyboard first time.

    • Turn on Bounce Keys to ignore key presses that are rapidly repeated. This can help, for example, if you have hand tremors which cause you to press a key multiple times when you only want to press it once.

  • Turn on Mouse Keys to control the mouse pointer using the numeric keypad on your keyboard.

  • Click Click Assist to open a dialog where you can enable various features that make clicking easier: simulated secondary click and hover click.

    • Turn on Simulated Secondary Click to activate the secondary click (usually the right mouse button) by holding down the primary button for a predefined Acceptance delay. This is useful if you find it difficult to move your fingers individually on one hand, or if your pointing device only has a single button.

    • Turn on Hover Click to trigger a click by hovering your mouse pointer over an object on the screen. This is useful if you find it difficult to move the mouse and click at the same time. If this feature is turned on, a small Hover Click window opens and stays above all of your other windows. You can use this to choose what sort of click should happen when you hover. When you hover your mouse pointer over a button and do not move it, the pointer gradually changes color. When it has fully changed color, the button will be clicked.

  • Use the slider to adjust the Double-Click Delay according to your needs.

4.5 For More Information

You can find further information in the GNOME help, which is also available online at https://help.gnome.org/users/gnome-help/3.20/a11y.html.en.

Part II Connectivity, Files and Resources

5 Accessing Network Resources

From your desktop, you can access files and directories or certain services on remote hosts or make your own files and directories available to other users in your network. SUSE® Linux Enterprise Server offers the following ways of accessing and creating network shared resources.

6 Managing Printers

SUSE® Linux Enterprise Server makes it easy to print your documents, whether your computer is connected directly to a printer or linked remotely on a network. This chapter describes how to set up printers in SUSE Linux Enterprise Server and manage print jobs.

7 Backing Up User Data

The Backup tool is a simple framework to let users back up and restore their own data such as home directories or selected files. It is possible to create scheduled backups or backups on request, and to play back a previous state of this data.

8 Passwords and Keys: Signing and Encrypting Data

The GNOME Passwords and Keys program is an important component of the encryption infrastructure on your system. With this program, you can create and manage PGP and SSH keys, import, export and share keys, back up your keys and keyring, and cache your passphrase.

9 gFTP: Transferring Data from the Internet

gFTP is a multithreaded file transfer client. It supports the FTP, FTPS (control connection only), HTTP, HTTPS, SSH, and FSP protocols. Furthermore, it allows the transfer of files between two remote FTP servers via FXP. To start gFTP, click Applications › Internet › gFTP.

5 Accessing Network Resources

  • Filename: gnome_networking.xml
  • ID: cha.gnome.network

From your desktop, you can access files and directories or certain services on remote hosts or make your own files and directories available to other users in your network. SUSE® Linux Enterprise Server offers the following ways of accessing and creating network shared resources.

Network Browsing

Your file manager, GNOME Files, lets you browse your network for shared resources and services. Learn more about this in Section 5.3, “Accessing Network Shares”.

Sharing Directories in Mixed Environments

Using GNOME Files, configure your files and directories to share with other members of your network. Make your data readable or writable for users from any Windows or Linux workstation. Learn more about this in Section 5.4, “Sharing Directories”.

Managing Windows Files

SUSE Linux Enterprise Server can be configured to integrate into an existing Windows network. Your Linux machine then behaves like a Windows client. It takes all account information from the Active Directory domain controller, just as the Windows clients do. Learn more about this in Section 5.5, “Managing Windows Files”.

Configuring and Accessing a Windows Network Printer

You can configure a Windows network printer through the GNOME control center. Learn how to do this in Section 5.6, “Configuring and Accessing a Windows Network Printer”.

5.1 Connecting to a Network

You can connect to a network with wired and wireless connections. To view your network connection, check the network icon in the right part of the main panel. If you click the icon, you can see more details in the menu. Click the connection name to see more details and access the settings.

To learn more about connecting to a network, see Chapter 36, Using NetworkManager.

5.2 General Notes on File Sharing and Network Browsing

Important
Important: Contact Your Administrator Before Setup

Whether and to what extent you can use file sharing and network browsing and in your network highly depends on the network structure and on the configuration of your machine.

Before setting up either of them, contact your system administrator. Check whether your network structure supports a feature and whether your company's security policies permit it.

Network browsing, be it SMB browsing for Windows shares or SLP browsing for remote services, relies heavily on the machine's ability to send broadcast messages to all clients in the network. These messages and the clients' replies to them enable your machine to detect any available shares or services.

For broadcasts to work effectively, your machine must be part of the same subnet as all other machines it is querying. If network browsing does not work on your machine or the detected shares and services do not meet your expectations, contact your system administrator to ensure that you are connected to the appropriate subnet.

To allow network browsing, your machine needs to keep several network ports open to send and receive network messages that provide details on the network and the availability of shares and services. The standard SUSE Linux Enterprise Server is configured for tight security and has a firewall that protects your machine against the Internet.

To adjust the firewall configuration, you either need to ask your system administrator to put your interface into the internal zone or to tear down the firewall entirely (depending on your company's security policy). If you try to browse a network while a restrictive firewall is running on your machine, GNOME Files warns you that your security restrictions are not allowing it to query the network.

5.3 Accessing Network Shares

Networking workstations can be set up to share directories. Typically, files and directories are marked to allow users remote access. These are called network shares. If your system is configured to access network shares, you can use your file manager to access these shares and browse them just as easily as if they were located on your local machine. Your level of access to the shared directories (whether read-only or write access, as well) is dependent on the permissions granted to you by the owner of the shares.

To access network shares, open GNOME Files and click Other Locations in the sidebar. GNOME Files displays the servers and networks that you can access. Double-click a server or network to access its shares. You might be required to authenticate to the server by providing a user name and password. Common network shares are SFTP-accessible resources (SSH File Transfer Protocol) or Windows shares.

Network File Browser
Figure 5.1: Network File Browser
Procedure 5.1: Adding a Network Place
  1. Open GNOME Files and click Other Locations in the sidebar. It shows a Connect to Server text box.

  2. Enter the server address.

  3. Click Connect.

5.4 Sharing Directories

Sharing and exchanging documents is a must-have in corporate environments. GNOME Files offers you file sharing, which makes your files and directories available to both Linux and Windows users.

5.4.1 Enabling Sharing on the Computer

Before you can share a directory, you must enable sharing on your computer. To enable sharing:

  1. Start YaST from the main menu.

  2. Enter the root password.

  3. In the category Network Services, click Windows Domain Membership.

  4. Click Allow Users to Share Their Directories, then click OK.

5.4.2 Enabling Sharing for a Directory

To configure file sharing for a directory:

  1. Open GNOME Files.

  2. Right-click a directory, select Properties and click Share.

  3. Select Share this folder.

  4. If you want other people to be able to write to the directory, select Allow others to create and delete files in this folder. To allow access for people without a user account check Guest Access.

  5. Click Create Share.

  6. If the directory does not already have the permissions that are required for sharing, a dialog appears. Click Add the permissions automatically.

The directory icon changes to indicate that the directory is now shared.

Important
Important: Samba Domain Browsing and Firewalls

Samba domain browsing only works if your system's firewall is configured accordingly. Either disable the firewall entirely or assign the browsing interface to the internal firewall zone. Ask your system administrator how to proceed.

5.5 Managing Windows Files

With your SUSE Linux Enterprise Server machine being an Active Directory client, you can browse, view and manipulate data located on Windows servers. The following examples are the most prominent ones:

Browsing Windows Files with GNOME Files

Use GNOME Files's network browsing features to browse your Windows data.

Viewing Windows Data with GNOME Files

Use GNOME Files to display the contents of your Windows user directory as you would for displaying a Linux directory. Create new files and directories on the Windows server.

Manipulating Windows Data with GNOME Applications

Many GNOME applications allow you to open files on the Windows server, manipulate them and save them back to the Windows server.

Single Sign-On

GNOME applications, including GNOME Files, support Single Sign-On. This means that you do not need to re-authenticate when you access other Windows resources. These can be Web servers, proxy servers or groupware servers like Microsoft Exchange*. Authentication against all these is handled silently in the background using the user name and password you provided when you logged in.

To access your Windows data using GNOME Files, proceed as follows:

  1. Open GNOME Files and click Network in the Places pane.

  2. Double-click Windows Network.

  3. Double-click the icon of the workgroup containing the computer you want to access.

  4. Click the computer’s icon (and authenticate if prompted to do so) and navigate to the shared directory on that computer.

To create directories in your Windows user directory using GNOME Files, proceed as you would when creating a Linux directory.

5.6 Configuring and Accessing a Windows Network Printer

Being part of a corporate network and authenticating against a Windows Active Directory server, you can access corporate resources such as printers. GNOME allows you to configure printing from your Linux client to a Windows network printer.

To configure a Windows network printer for use through your Linux workstation, proceed as follows:

  1. Start the GNOME control center from the main menu by clicking Applications › System Tools › Settings › Printers.

    Note
    Note: Starting the CUPS Service

    The CUPS service is not started by default after installation of SUSE Linux Enterprise Server. If the Printers dialog shows a message that the printing service is currently not available, you need to start the CUPS service manually.

    Start it by opening a shell and typing:

    sudo systemctl start cups
  2. Click Unlock and enter the root password.

  3. Click the plus icon.

  4. Select a Windows printer connected via Samba.

To print to the Windows network printer configured above, select it from the list of available printers.

6 Managing Printers

  • Filename: gnome_print.xml
  • ID: cha.gnome.print

SUSE® Linux Enterprise Server makes it easy to print your documents, whether your computer is connected directly to a printer or linked remotely on a network. This chapter describes how to set up printers in SUSE Linux Enterprise Server and manage print jobs.

6.1 Installing a Printer

Before you can install a printer, you need to know the root password and have your printer information ready. Depending on how you connect the printer, you might also need the printer URI, TCP/IP address or host, and the driver for the printer. A number of common printer drivers ship with SUSE Linux Enterprise Server. If you cannot find a driver for the printer, check the printer manufacturer's Web site.

  1. Click Applications › System Tools › Settings › Printers.

  2. Click Unlock and enter the root password.

  3. Click the plus icon.

  4. If there are too many printers in the list, filter them by entering an IP address or a keyword into the search field in the lower part of the dialog.

  5. Select a printer from the list of available printers and click Add.

The installed printer appears in the Printers panel. You can now print to the printer from any application.

7 Backing Up User Data

  • Filename: backup.xml
  • ID: cha.userbackup
Abstract

The Backup tool is a simple framework to let users back up and restore their own data such as home directories or selected files. It is possible to create scheduled backups or backups on request, and to play back a previous state of this data.

7.1 Creating Backups

First schedule which data you want to back up and when to do it.

  1. Click Applications › System Tools › Backup.

  2. If you are opening the application for the first time, you will see a screen welcoming you. Click Just show my backup settings.

  3. On the Overview tab you can turn the Automatic backups on and off. You can also see the overview of the current settings.

  4. On the Storage tab, select a Backup Location and a Folder to which the backup should be written.

  5. On the Folders tab select the directories to back up and directories to ignore. For example, if you want to back up your home directory except for the Downloads directory, add your home directory to the category Folders to back up and your Downloads directory to the category Folders to ignore.

  6. On the Schedule tab select how often to perform the automatic backups (daily or weekly) and how long to keep the backups.

  7. (Optional) If you want to perform a backup immediately, too, switch back to the Overview tab and click Back Up Now.

    1. Choose whether you want the backup to be password-protected.

      If so, type a password in the two text boxes next to Encryption Password and Confirm Password.

      If not, click Allow Restoring Without a Password.

    2. Click Continue to start the backup process. When the backup is finished, the window will close.

7.2 Restoring Data

To restore a previous state of your data, proceed as follows:

  1. Select Applications › System Tools › Backup.

  2. On the Overview tab, click Restore.

  3. Choose the location from which to restore. Click Forward. The tool searches for backups stored in that location.

  4. Choose a date. Click Forward.

  5. Choose whether to restore the files to the original location or to another directory. Click Forward to see a summary of your choices.

  6. Click Restore to start the restoration process.

8 Passwords and Keys: Signing and Encrypting Data

  • Filename: gnome_crypto.xml
  • ID: cha.gnome.crypto

The GNOME Passwords and Keys program is an important component of the encryption infrastructure on your system. With this program, you can create and manage PGP and SSH keys, import, export and share keys, back up your keys and keyring, and cache your passphrase.

Start the program by choosing Applications › Utilities › Passwords and Keys

Password and Keys Main Window
Figure 8.1: Password and Keys Main Window

8.1 Signing and Encryption

Signing.  Attaching electronic signatures to pieces of information, such as e-mail messages or software to prove its origin. To keep someone else from writing messages using your name, and to protect both you and the people you send them to, you should sign your mails. Signatures help you check the sender of the messages you receive and distinguish authentic messages from malicious ones.

Software developers sign their software so that you can check the integrity. Even if you get the software from an unofficial server, you can verify the package with the signature.

Encryption.  You might also have sensitive information you want to protect from other parties. Encryption helps you transform data and make it unreadable for others. This is important for companies so they can protect internal information and their employees' privacy.

8.2 Generating a New Key Pair

To exchange encrypted messages with other users, you must first generate your own pair of keys. It consists of two parts:

  • Public Key.  This key is used for encryption. Distribute it to your communication partners, so they can use it to encrypt files or messages for you.

  • Private Key.  This key is used for decryption. Use it to make encrypted files or messages from others (or yourself) legible again.

Important
Important: Access to the Private Key

If others gain access to your private key, they can decrypt files and messages intended only for you. Never grant others access to your private key.

8.2.1 Creating OpenPGP Keys

OpenPGP is a non-proprietary protocol for encrypting e-mail with the use of public-key cryptography based on PGP. It defines standard formats for encrypted messages, signatures, private keys, and certificates for exchanging public keys.

  1. Click Applications › Utilities › Passwords and Keys.

  2. Click File › New.

  3. Select PGP Key and click Continue.

  4. Specify your full name and e-mail address.

  5. Click Advanced key options to specify the following advanced options for the key.

    Comment

    An optional comment.

    Encryption Type

    Specifies the encryption algorithms used to generate your keys. DSA ElGamal is the recommended choice because it lets you encrypt, decrypt, sign, and verify as needed. Both DSA (sign only) and RSA (sign only) allow only signing.

    Key Strength

    Specifies the length of the key in bits. The longer the key, the more secure it is (provided a strong passphrase is used). Keep in mind that performing any operation with a longer key requires more time than it does with a shorter key. Acceptable values are between 1024 and 4096 bits. At least 2048 bits are recommended.

    Expiration Date

    Specifies the date at which the key will cease to be usable for performing encryption or signing operations. You will need to either change the expiration date or generate a new key or subkey after this amount of time passes. Sign your new key with your old one before it expires to preserve your trust status.

  6. Click Create to create the new key pair.

    The Passphrase for New PGP Key dialog opens.

  7. Specify the passphrase twice for your new key, then click OK.

    When you specify a passphrase, use the same practices you use when you create a strong password.

8.2.2 Creating Secure Shell Keys

Secure Shell (SSH) is a method of logging in to a remote computer to execute commands on that machine. SSH keys are used in key-based authentication system as an alternative to the default password authentication system. With key-based authentication, there is no need to manually type a password to authenticate.

  1. Click Applications › Utilities › Passwords and Keys.

  2. Click File › New.

  3. Select Secure Shell Key, then click Continue.

  4. Specify a description of what the key is to be used for.

    You can use your e-mail address or any other reminder.

  5. Optionally, click Advanced key options to specify the following advanced options for the key.

    Encryption Type.  Specifies the encryption algorithms used to generate your keys. Select RSA to use the Rivest-Shamir-Adleman (RSA) algorithm to create the SSH key. This is the preferred and more secure choice. Select DSA to use the Digital Signature Algorithm (DSA) to create the SSH key.

    Key Strength.  Specifies the length of the key in bits. The longer the key, the more secure it is (provided a strong passphrase is used). Keep in mind that performing any operation with a longer key requires more time than it does with a shorter key. Acceptable values are between 1024 and 4096 bits. At least 2048 bits is recommended.

  6. Click Just Create Key to create the new key, or click Create and Set Up to create the key and set up another computer to use for authentication.

  7. Specify the passphrase for your new key, click OK, then repeat.

    When you specify a passphrase, use the same practices you use when you create a strong password.

8.3 Modifying Key Properties

You can modify properties of existing OpenPGP or SSH keys.

8.3.1 Editing OpenPGP Key Properties

The descriptions in this section apply to all OpenPGP keys.

  1. Click Applications › Utilities › Passwords and Keys.

  2. Double-click the PGP key you want to view or edit.

  3. Use the options on the Owner tab to add a photo to the key or to change the passphrase associated with the key.

    Photo IDs allow a key owner to embed one or more pictures of themselves in a key. These identities can be signed like normal user IDs. A photo ID must be in JPEG format. The recommended size is 120×150 pixels.

    If the chosen image does not meet the required file type or size, Passwords and Keys can resize and convert it on the fly from any image format supported by the GDK library.

  4. Click the Names and Signatures tab to add a user ID to a key.

    See Section 8.3.1.1, “Adding a User ID” for more information.

  5. Click the Details tab, which contains the following properties:

    Key ID:  The Key ID is similar to the Fingerprint, but the Key ID contains only the last eight characters of the fingerprint. It is generally possible to identify a key with only the Key ID, but sometimes two keys might have the same Key ID.

    Type:  Specifies the encryption algorithm used to generate a key. DSA keys can only sign. ElGamal keys are used to encrypt.

    Strength:  Specifies the length, in bits, of the key. The longer the key, the more security it provides. However, a long key will not compensate for the use of a weak passphrase.

    Fingerprint:  A unique string of characters that exactly identifies a key.

    Created:  The date the key was created.

    Expires:  The date the key can no longer be used (a key can no longer be used to perform key operations after it has expired). Changing a key's expiration date to a point in the future re-enables it. A good general practice is to have a master key that never expires and multiple subkeys that do expire and are signed by the master key.

    Override Owner Trust:  Here you can set the level of trust in the owner of the key. Trust is an indication of how sure you are of a person's ability to correctly extend the Web of trust. When there is a key that you have not signed, the validity of the key is determined from its signatures and how much you trust the people who made those signatures.

    Export Secret Key:  Exports the key to a file.

    Subkeys:  See Section 8.3.1.2, “Editing OpenPGP Subkey Properties” for more information.

  6. Click Close.

8.3.1.1 Adding a User ID

User IDs allow multiple identities and e-mail addresses to be used with the same key. Adding a user ID is useful, for example, when you want to have an identity for your job and one for your friends. They take the following form:

Name (COMMENT) <E-MAIL>
  1. Click Applications › Utilities › Passwords and Keys.

  2. Double-click the PGP key you want to view or edit.

  3. Click the Names and Signatures tab, then click Add Name.

  4. Specify a name in the Full Name field.

    You must enter at least five characters in this field.

  5. Specify an e-mail address in the E-Mail Address field.

    Your e-mail address is how most people will locate your key on a key server or other key provider. Make sure it is correct before continuing.

  6. In the Key Comment field, specify additional information that will display in the name of your new ID.

    This information can be searched for on key servers.

  7. Confirm your changes and enter the passphrase when prompted for it.

8.3.1.2 Editing OpenPGP Subkey Properties

Each OpenPGP key has a single master key used to sign only. Subkeys are used to encrypt and to sign as well. In this way, if your subkey is compromised, you do not need to revoke your master key.

  1. Click Applications › Utilities › Passwords and Keys.

  2. Double-click the PGP key you want to edit.

  3. Click the Details tab, then click to show the Subkeys category.

  4. Use the buttons on the left of the dialog to add, delete, expire, or revoke subkeys.

    Each subkey has the following information:

    ID:  The identifier of the subkey.

    Type:  Specifies the encryption algorithm used to generate a subkey. DSA keys can only sign, ElGamal keys are used to encrypt, and RSA keys are used to sign or to encrypt.

    Usage:  Shows if the key can be used to sign, to certify, or also to encrypt.

    Created:  Specifies the date the key was created.

    Expires:  Specifies the date the key can no longer be used.

    Status:  Specifies the status of the key.

    Strength:  Specifies the length, in bits, of the key. The longer the key, the more security it provides. However, a long key will not compensate for the use of a weak passphrase.

  5. Click Close.

8.3.2 Editing Secure Shell Key Properties

The descriptions in this section apply to all SSH keys.

  1. Click Applications › Utilities › Passwords and Keys.

  2. Double-click the Secure Shell key you want to view or edit.

  3. Use the options on the Key tab to change the name of the key or the passphrase associated with the key.

  4. Click the Details tab, which contains the following properties:

    Algorithm:  Specifies the encryption algorithm used to generate a key.

    Strength:  Indicates the length in bits of a key. The longer the key, the more security it provides. However, a long key does not make up for the use of a weak passphrase.

    Location:  The location where the private key has been stored.

    Fingerprint:  A unique string of characters that exactly identifies a key.

    Export Complete Key:  Exports the key to a file.

  5. Click Close.

8.4 Importing Keys

Keys can be exported to text files. These files contain human-readable text at the beginning and at the end of a key. This format is called an ASCII-armored key.

To import keys:

  1. Click Applications › Utilities › Passwords and Keys.

  2. Click File › Import.

  3. Select a file containing at least one ASCII-armored public key.

  4. Click Open to import the key.

You can also paste keys inside Passwords and Keys:

  1. Select an ASCII-armored public block of text, then copy it to the clipboard.

  2. Click Applications › Utilities › Passwords and Keys.

  3. Click Edit › Paste

8.5 Exporting Keys

To export keys:

  1. Click Applications › Utilities › Passwords and Keys.

  2. Select the keys you want to export.

  3. Click File › Export.

  4. Specify a file name and location for the exported key.

  5. Click Save to export the key.

You can also export keys to the clipboard in an ASCII-armored block of text:

  1. Click Applications › Utilities › Passwords and Keys.

  2. Select the keys you want to export.

  3. Click Edit › Copy.

8.6 Signing a Key

Signing another person's key means that you are giving trust to that person. Before signing a key, carefully check the key's fingerprint to ensure that the key really belongs to that person.

Trust is an indication of how sure you are of a person's ability to correctly extend the Web of trust. When there is a key that you have not signed, the validity of the key is determined from its signatures and how much you trust the people who made those signatures.

  1. Click Applications › Utilities › Passwords and Keys.

  2. Select the key you want to sign from the My Personal Keys or Other Keys tabs.

  3. Click File › Sign.

  4. Select how carefully the key has been checked, then indicate if the signature should be local to your keyring, and if your signature can be revoked:

  5. Click Sign.

8.7 Password Keyrings

You can use password keyring preferences to create or remove keyrings, to set the default keyring for application passwords or to change the unlock password of a keyring. To create a new keyring, follow these steps:

  1. Click Applications › Utilities › Passwords and Keys.

  2. Click File › New › Password Keyring, then click Continue.

  3. Enter a name for the keyring and click Add.

  4. Set and confirm a new Password for the keyring and click Create.

To change the unlock password of an existing keyring, right-click the keyring in the Passwords tab and click Change Password. You need to provide the old password to be able to change it.

To change the default keyring for application passwords, right-click the keyring in the Passwords tab and click Set as Default.

8.8 Key Servers

You can keep your keys up-to-date by synchronizing keys periodically with remote keyservers. Synchronizing will ensure that you have the latest signatures made on all of your keys, so that the Web of trust will be effective.

  1. Click Applications › Utilities › Passwords and Keys.

  2. Click Edit › Preferences, then click the Key Servers tab.

    Passwords and Keys provides support for HKP and LDAP keyservers.

    HKP Key Servers:  HKP key servers are ordinary Web-based key servers, such as the popular hkp://pgp.mit.edu:11371, also accessible at http://pgp.mit.edu.

    LDAP Key Servers:  LDAP key servers are less common, but use the standard LDAP protocol to serve keys. ldap://keyserver.pgp.com is a good LDAP server.

    You can Add or Remove key servers to be used using the buttons on the left. To add a new key server, set its type, host and port, if necessary.

  3. Set whether you want to automatically publish your public keys and which keyserver to use. Set whether you want to automatically retrieve keys from key servers and whether to synchronize modified keys with keyservers.

  4. Click Close.

8.9 Key Sharing

Key Sharing is provided by DNS-SD, also known as Bonjour or Rendezvous. Enabling key sharing adds the local Passwords and Keys users' public key rings to the remote search dialog. Using these local key servers is generally faster than accessing remote servers.

  1. Click Applications › Utilities › Passwords and Keys.

  2. Click Edit › Preferences, then click the Key Servers tab.

  3. Select Automatically synchronize modified keys with key servers.

  4. Click Close.

9 gFTP: Transferring Data from the Internet

  • Filename: apps_gftp.xml
  • ID: cha.gnome.gftp
Abstract

gFTP is a multithreaded file transfer client. It supports the FTP, FTPS (control connection only), HTTP, HTTPS, SSH, and FSP protocols. Furthermore, it allows the transfer of files between two remote FTP servers via FXP. To start gFTP, click Applications › Internet › gFTP.

gFTP—Main Window
Figure 9.1: gFTP—Main Window

9.1 ASCII Compared to Binary Transfers

There are two common ways of transferring files via FTP: ASCII and binary. ASCII mode transfers files as text. ASCII files are .txt, .asp, .html, and .php files, for example. Binary mode transfers files as raw data. Binary files are .wav, .jpg, .gif, and mp3 files, for example.

To change the transfer mode, click the FTP menu and select Binary or Ascii.

When transferring ASCII files from Linux/Unix to Windows or vice versa, open the Preferences dialog by clicking FTP › Preferences. Switch to the FTP tab and select Transfer Files in ASCII Mode to ensure that newline characters are correctly converted. This option will automatically be disabled in Binary mode.

9.2 Connecting to a Remote Server

To connect to a remote server, do the following:

  1. Click Remote › Open Location.

  2. Specify a URL to connect to and click Connect.

  3. Specify your user name and click Connect. Then specify your password and click Connect. To connect anonymously, leave the user name blank.

  4. If the connection is successful, the right part of the gFTP window lists files from the remote computer. The file listing on the left side continues to show files from your local computer. You can now upload and download files via drag and drop or by using the arrow buttons.

To bookmark a site you access frequently, click Bookmarks › Add Bookmark. Specify a name for the bookmark, then click Add. The new bookmark is added to your list of bookmarks.

9.3 Transferring Files

In the following figure, the file list on the right contains the remote server's directory of files. The file list on the left side contains your local computer's directory of files (on your hard disk or network).

gFTP File Transfer
Figure 9.2: gFTP File Transfer

To download files, select the files you want to download in the remote list of files, then click the arrow button pointing to the left. The progress of each download is listed in the field in the middle of the window. If the transfer is successful, the files appear in the directory listing on the left.

To upload a file, select the files you want to upload in your local directory listing on the left, then click the arrow button pointing to the right. The progress of each download is listed in the field in the middle of the window. If the transfer is successful, the files appear in the remote directory listing on the right.

To modify preferences for your downloads, select FTP › Preferences from the menu.

9.4 Setting Up an HTTP Proxy Server

To set up an HTTP proxy server, do the following:

  1. From the menu, select FTP › Preferences, then select the FTP tab.

  2. Enter the Proxy hostname and Proxy port. If applicable, also provide your login credentials for the proxy server. Choose a proxy type from the Proxy Server Type drop-down box.

  3. Click the HTTP tab, and enter the same proxy server information in the dialog as described above. Port numbers for FTP and HTTP proxy may differ.

  4. Click OK.

9.5 For More Information

You can find more information about gFTP at http://www.gftp.org.

Part III LibreOffice

10 LibreOffice: The Office Suite

LibreOffice is an open source office suite that provides tools for all types of office tasks such as writing texts, working with spreadsheets, or creating graphics and presentations. With LibreOffice, you can use the same data across different computing platforms. You can also open and edit files in other formats, including Microsoft* Office* formats, then save them back to this format, if needed. This chapter contains information that applies to all LibreOffice modules.

11 LibreOffice Writer

LibreOffice Writer is a full-featured word processor with page and text formatting capabilities. Its interface is similar to interfaces of other major word processors, and it includes some features that are usually found only in desktop publishing applications.

This chapter highlights a few key features of Writer. For more information about these features and for complete instructions for using Writer, look at the LibreOffice help or at the sources listed in Section 10.10, “For More Information”.

Much of the information in this chapter can also be applied to other LibreOffice modules. For example, other modules use styles similarly to how they are used in Writer.

12 LibreOffice Calc

Calc is the LibreOffice spreadsheet module. Spreadsheets consist of several sheets, containing cells which can be filled with elements like text, numbers, or formulas. A formula can manipulate data from other cells to generate a value for the cell in which it is inserted. Calc also allows you to def…

13 LibreOffice Impress, Base, Draw, and Math

Besides LibreOffice Writer and LibreOffice Calc, LibreOffice also includes the modules Impress, Base, Draw, and Math. With these you can create presentations, design databases, draw up graphics and diagrams, and create mathematical formulas.

10 LibreOffice: The Office Suite

  • Filename: apps_libreoffice.xml
  • ID: cha.oo.oview
Abstract

LibreOffice is an open source office suite that provides tools for all types of office tasks such as writing texts, working with spreadsheets, or creating graphics and presentations. With LibreOffice, you can use the same data across different computing platforms. You can also open and edit files in other formats, including Microsoft* Office* formats, then save them back to this format, if needed. This chapter contains information that applies to all LibreOffice modules.

10.1 LibreOffice Modules

LibreOffice consists of several application modules (subprograms) which are designed to integrate with each other. While this chapter contains information that applies to all LibreOffice modules, the following chapters and sections contain information on individual modules. Find a short description and where each module is described in Table 10.1, “The LibreOffice Application Modules”.

A full description of each module is available in the application help, described in Section 10.10, “For More Information”.

Table 10.1: The LibreOffice Application Modules

Module

Purpose

Described in

Writer

Word processor module

Chapter 11

Calc

Spreadsheet module

Chapter 12

Impress

Presentation module

Section 13.1

Base

Database module

Section 13.2

Draw

Module for drawing vector graphics

Section 13.3

Math

Module for generating mathematical formulas

Section 13.4

10.2 Starting LibreOffice

To start LibreOffice, click Applications › Office › LibreOffice. In the LibreOffice start center, choose the type of document you want to create.

There are multiple methods to directly start one of the LibreOffice modules:

  • If any LibreOffice module is open, you can start any of the other modules by clicking File › New and then selecting the type of document you want to create.

  • You can also start individual LibreOffice modules from the menu Applications.

  • As an alternative, use the command libreoffice and one of the options --writer, --calc, --impress, --draw, or --base to start the respective module.

    LibreOffice has many command line options, especially for allowing document conversions. To learn more about the command line options of LibreOffice, see libreoffice --help or the man page of LibreOffice (man libreoffice(1)).

Before you start working with LibreOffice, you may be interested in changing some options from the preferences dialog. Click Tools › Options to open it. The most important ones are:

LibreOffice › User Data

Specify your user data such as company, first and last name, street, city, and other useful information. This data has many uses: It is used in the comment functions of Writer and Calc, for authorship information in PDF documents, and for serial letters in Writer.

LibreOffice › Fonts

Map font names to installed fonts. This can be useful if you exchange documents with others and the document you received contains fonts that are not available on your system.

Load/Save › General

Contains loading and saving specific options. For example, you can choose whether to always create a backup copy and which file format LibreOffice should use by default.

To learn more about configuring LibreOffice, see Section 10.7, “Changing the Global Settings”.

10.3 The LibreOffice User Interface

The user interface of most of LibreOffice is very similar across its modules:

Menu Bar

At the top of the application, there is the menu bar which gives access to almost all functionality of LibreOffice. The menu bar can be customized to include more or fewer functions. You can also add and remove menus.

Toolbars

By default, the toolbars are positioned directly below the menu bar. The toolbars comprise the most used and most important items of the module.

To dock a toolbar to any other side of the window, drag it to the right position. To make a toolbar float, drag it into the middle of the window. They can be customized to include more or fewer functions. You can also add and remove toolbars.

Side Bar

By default, the side bar is positioned at the right side of the LibreOffice window. On the first start of LibreOffice, it is only visible as several icons stacked vertically. Clicking one of the icons opens a panel with more elements. Click the icon again to close the panel. Similarly to the toolbars, the side bar comprises the most important functions.

To dock the side bar to the left or right side of the window, drag it to the right position. To make the side bar float, drag it into the middle of the window. To hide the side bar, click the vertical arrowhead button on the document-facing side of the side bar.

You can hide or show side bar panels but cannot customize their functionality.

Statusbar

The statusbar is displayed at the bottom of the window. It mainly shows information about the document, such as the number of words (in Writer) or the sum of values of selected cells (in Calc). However, it can also be used to change the zoom or language settings. Many elements open additional menus or dialogs on left click, right click, or double click.

For more information on customizing LibreOffice, see Section 10.6, “Customizing LibreOffice”.

10.4 Compatibility with Other Office Applications

The native file format of LibreOffice is the OpenDocument format. OpenDocument is an ISO-standardized format for office documents that is based on XML. However, LibreOffice can also work with documents, spreadsheets, presentations, and databases in many other formats, including Microsoft Office formats. Files in Microsoft Office formats can be opened and saved back normally.

10.4.1 Opening Documents from Other Office Suites

If you use LibreOffice in an environment where you need to share documents with Microsoft Word users, you should have little or no trouble exchanging document files. However, very complex documents can require editing after opening. Complex documents are documents containing, for example, complicated tables, Microsoft Office macros, or unusual fonts, formatting, or graphical objects.

In case there should ever be issues with opening documents, try the following strategies:

  • Text Documents.  Consider opening text documents in the original application and saving them as RTF or plain text (TXT). However, saving as plain text means that all formatting will be lost.

  • Spreadsheets.  Consider opening spreadsheets in the original application and saving them as Excel files. If this does not work, try the CSV format. However, saving as CSV means that all formatting, cell type definitions, formulas, and macros will be lost.

10.4.2 Converting Documents to the OpenDocument Format

LibreOffice can read, edit, and save documents in several formats. It is not necessary to convert files from those formats to the OpenDocument format used by LibreOffice to use those files. However, if you want to convert the files, you can do so. To convert several documents, such as when first switching to LibreOffice, do the following:

  1. Select File › Wizards › Document Converter.

  2. Choose the file format from which to convert.

  3. Click Next.

  4. Specify where LibreOffice should look for templates and documents to convert and in which directory the converted files should be placed.

    Documents retrieved from a Windows partition are usually in a subdirectory of /windows.

  5. Make sure that all other settings are correct, then click Next.

  6. Review the summary of the actions to perform, then start the conversion by clicking Convert.

    The amount of time needed for the conversion depends on the number of files and their complexity. For most documents, conversion does not take long.

  7. When everything is done, close the Wizard.

10.4.3 Sharing Files with Users of Other Office Suites

LibreOffice is available for several operating systems. This makes it an excellent tool when a group of users frequently need to share files and do not use the same system on their computers.

When sharing documents with others, you have several options:

If the recipient needs to be able to edit the file

Save the document in the format the other user needs. For example, to save as a Microsoft Word file, click File › Save As, then select the Microsoft Word file type for the version of Word the other user needs.

If the recipient only needs to read the document

Export the document to a PDF file with File › Export as PDF. PDF files can be read on any platform using a PDF viewer.

Sharing a document for editing

Agree on a common exchange format that works for everyone. TXT and RTF formats, although limited in formatting, can be a good option for text documents.

E-mailing a document as a PDF

Click File › Send › E-mail as PDF. Your default e-mail program opens with the file attached.

E-mailing a document to a Microsoft Word user

Click File › Send › E-mail as Microsoft Word. Your default e-mail program opens with the file attached.

10.5 Saving Files with a Password

You can save files, no matter in which LibreOffice format, with a password. Unlike older versions of LibreOffice, the encryption applied to the document with recent versions of LibreOffice is very strong. However, this encryption does not protect file names and file sizes of encrypted files. If that is important to you, see the alternate encryption methods described in Chapter 11, Encrypting Partitions and Files.

Procedure 10.1:
  1. To save a file with a password, select File › Save or File › Save As.

  2. In the dialog that opens, activate the check box Save with password at the bottom and click Save.

  3. Type and confirm your password, then click OK.

The next time you open the file, you will be prompted for the password.

To change the password, do either of the following:

  • Overwrite the same file by selecting File › Save As. Make sure Save with Password is deactivated.

  • Select File › Properties and click Change Password to access the password dialog.

10.6 Customizing LibreOffice

You can customize LibreOffice to best suit your needs and working style. Toolbars, menus, and key combinations can all be reconfigured to help you more quickly access the features you use the most.

You can also assign macros to application events if you want specific actions to occur when those events take place. For example, if you always work with a specific spreadsheet, you can create a macro that opens the spreadsheet and assign the macro to the Start Application event.

This section contains simple, generic instructions for customizing your environment. The changes you make are effective immediately. This means you can see if the changes are what you wanted and go back and modify them if they are not. See the LibreOffice help files for detailed instructions.

To access the customization dialog in any open LibreOffice module, select Tools › Customize.

Customization Dialog in Writer
Figure 10.1: Customization Dialog in Writer
Note
Note: Further Information

Click Help for more information about the options in the Customize dialog.

Procedure 10.2: Customizing Toolbars
  1. In the customization dialog, click the tab Toolbar.

  2. From the drop-down box Toolbar, select the toolbar you want to customize.

  3. Activate the check boxes next to the commands you want to appear on the toolbar, and deactivate the check boxes next to the commands you do not want to appear. A short description for each command is shown at the bottom of the dialog.

  4. With Save In, select whether to save your customized toolbar in the current LibreOffice module or in the current document. If you decide to save it in the LibreOffice module, the customized toolbar is used whenever you open that module. If you decide to save it together with the current document, the customized toolbar is used whenever you open that document.

  5. Repeat to customize additional toolbars.

  6. Click OK.

To switch back to the original settings again, open the customization dialog, click the Toolbar drop-down box and select Restore Default Settings. Click Yes and Reset to proceed.

Procedure 10.3: Showing or Hiding Buttons in the Toolbar
  1. Click the arrow icon at the right edge of the toolbar you want to change.

  2. Click Visible Buttons to display a list of buttons.

  3. Select the buttons in the list to enable (check) or disable (uncheck) them.

Procedure 10.4: Customizing Menus

You can add or delete items from current menus, reorganize menus, and even create new menus.

  1. Click Tools › Customize › Menus.

  2. Select the menu you want to change, or click New to create a new menu.

  3. Modify, add, or delete menu items as desired.

  4. Click OK.

Procedure 10.5: Customizing Key Combinations

You can reassign currently assigned key combinations and assign new ones to frequently used functions.

  1. Click Tools › Customize › Keyboard.

  2. Select the keys you want to assign to a combination.

  3. Select a Category and an appropriate function.

  4. Click Modify to assign the function to the key or Delete to remove an existing assignment.

  5. Click OK.

Procedure 10.6: Customizing Events

LibreOffice also provides ways to assign macros to events such as application start-up or the saving of a document. The assigned macro runs automatically whenever the selected event occurs.

  1. Click Tools › Customize › Events.

  2. Select the event you want to change.

  3. Assign or remove macros for the selected event.

  4. Click OK.

10.7 Changing the Global Settings

Global settings can be changed in any LibreOffice module by clicking Tools › Options on the menu bar. This opens the window shown in the figure below. A tree structure is used to display categories of settings.

The Options Window
Figure 10.2: The Options Window

The settings categories that appear depend on the module you are working in. For example, if you are in Writer, the LibreOffice Writer category appears in the list, but the LibreOffice Calc category does not. The LibreOffice Base category appears in both Calc and Writer. The Module column in the table shows where each setting category is available.

The following table lists the settings categories along with a brief description of each category:

Table 10.2: Global Setting Categories

Settings Category

Description

Module

LibreOffice

Basic settings, including your user data (such as your address and e-mail), important paths, and settings for printers and external programs.

All

Load/Save

Settings related to the opening and saving of several file types. There is a dialog for general settings and several special dialogs to define how external formats should be handled.

All

Language Settings

Settings related to languages and writing aids, such as your locale and spell checker settings. This is also the place to enable support for Asian languages.

All

LibreOffice Writer

Settings related to word processing, such as the basic units, fonts and layout that Writer should use.

Writer

LibreOffice Writer/Web

Settings related to the HTML authoring features of LibreOffice.

Writer

LibreOffice Calc

Settings related to spreadsheets, such as spreadsheet appearance, Microsoft Excel compatibility options, and calculation options.

Calc

LibreOffice Impress

Settings related to presentations, such as enabling the smartphone remote control and the grid of the page to use.

Impress

LibreOffice Draw

Settings related to drawings, such as the grid of the page to use.

Draw

LibreOffice Base

Allows setting and editing database connections and registered databases.

Base

Charts

Allows defining the default colors used for newly created charts.

All

Internet

Allows configuring a proxy and the e-mail software to use.

All

Important
Important: Settings Apply Globally

All settings listed in the table apply globally for the specified modules. That means, they are used as defaults for every new document you create.

10.8 Using Templates

A template is a document containing only the styles—and content— that you want to appear in every document of that type. When a document is created or opened with the template, the styles are automatically applied to that document. Templates greatly enhance the use of LibreOffice by simplifying formatting tasks for a variety of different types of documents.

For example, in a word processor, you can write letters, memos, and reports, all of which look different and require different styles. Or, for example, for spreadsheets, you could use different cell styles or headings for certain types of spreadsheets. If you use templates for each of your document types, the styles you need for each document are always readily available.

LibreOffice comes with a set of predefined templates. You can also find additional templates on the Internet, for example at http://templates.libreoffice.org. For details, see Section 10.10, “For More Information”.

Creating your own templates requires some planning. You need to determine how you want the document to look, so you can create the styles you need in that template.

A detailed explanation of templates is beyond the scope of this section. Procedure 10.7, “Creating LibreOffice Templates” only shows how to generate a template from an existing document.

Procedure 10.7: Creating LibreOffice Templates

For text documents, spreadsheets, presentations, and drawings, you can create a template from an existing document as follows:

  1. Start LibreOffice and open or create a document that contains the styles and content that you want to re-use for other documents of that type.

  2. Click File › Templates › Save as Template.

  3. Choose a directory to save the image in by double-clicking one of the directory icons.

    If you are in a subdirectory and want to go up again, use the path bar displayed above the directories.

  4. From the toolbar, choose Save.

  5. Specify a name for the template.

  6. Click OK.

Note
Note: Converting Microsoft Word Templates

You can convert Microsoft Word templates like you would convert any other Word document. For more information, see Section 10.4.2, “Converting Documents to the OpenDocument Format”.

10.9 Setting Metadata and Properties

When exchanging documents with other people, it is sometimes useful to store metadata like the owner of the file, who it was received from, and a URL. LibreOffice lets you attach such metadata to the file. This helps you track metadata which you do not want to or cannot save in the content of the file. This feature is also the basis for later sorting, searching and retrieving your documents based on metadata.

As an example, we assume you want to set these properties to your file:

  • A title, subject, and some keywords

  • The owner of the file

  • Who sent you the file

To attach such metadata to your document, proceed as follows:

Procedure 10.8: Setting Properties
  1. Click File › Properties. A dialog opens. It has, among others, the following tabs:

  2. Change to the Description tab and insert title, subject, and your keywords.

  3. Switch to the Custom Properties tab.

  4. To add a row for a property, click Add.

  5. In the Name column, click the drop-down box for the entry. A list of properties appears, from it, choose Owner.

  6. Insert the name of the owner in the Value column.

  7. Repeat from Step 4 but as the name of the property, this time, choose Received from.

    Optionally, repeat from Step 4 for more properties.

    To remove a property, click the red icon at the end of the corresponding row.

  8. Leave the dialog with OK.

  9. Save the file.

10.10 For More Information

LibreOffice contains extensive online help. In addition, a large community of users and developers support it. The following list shows some places where you can go for additional information.

LibreOffice Application Help (Help › LibreOffice Help)

Extensive help on performing any task in LibreOffice.

https://www.libreoffice.org

Home page of LibreOffice

https://ask.libreoffice.org

Official question and answer page for LibreOffice.

http://www.taming-libreoffice.com/

Taming LibreOffice: books, news, tips and tricks.

http://www.pitonyak.org/oo.php

Extensive information about creating and using macros.

http://extensions.libreoffice.org/

Extension and template directory for LibreOffice.

https://www.worldlabel.com/Pages/openoffice-template.htm

Templates for creating labels with LibreOffice.

11 LibreOffice Writer

  • Filename: apps_librewriter.xml
  • ID: cha.oo.writer
Abstract

LibreOffice Writer is a full-featured word processor with page and text formatting capabilities. Its interface is similar to interfaces of other major word processors, and it includes some features that are usually found only in desktop publishing applications.

This chapter highlights a few key features of Writer. For more information about these features and for complete instructions for using Writer, look at the LibreOffice help or at the sources listed in Section 10.10, “For More Information”.

Much of the information in this chapter can also be applied to other LibreOffice modules. For example, other modules use styles similarly to how they are used in Writer.

11.1 Creating a New Document

There are multiple ways to create a new Writer document:

  • From Scratch.  To create a new empty document, click File › New › Text Document.

  • Using a Wizard.  To use a standard format and predefined elements for your own documents, use a wizard. Click File › Wizards › Letter and follow the steps.

  • From a Template.  To use a template, click File › New › Templates and open, for example, Business Correspondence. From the list of text document templates, select the one that fits your needs.

For example, to create a business letter, click File › Wizards › Letter. Using the wizard, you can easily create a basic document using a standard format. A sample wizard dialog is shown in Figure 11.1.

A LibreOffice Wizard
Figure 11.1: A LibreOffice Wizard

Enter text in the document window as desired. Use the tools for applying and changing styles or the tools for direct formatting to adjust the appearance of the document. Use the File menu or the relevant buttons in the toolbar to print and save your document. With the options under Insert, add extra items to your document, such as a table, picture, or chart.

11.2 Formatting with Styles

The traditional way of formatting office documents is direct formatting. That means, you use a button, such as Bold, which sets a certain property (in this case, a bold typeface). With styles, you can bundle a set of properties (for example, font size and font weight) and give them a speaking name, such as Headline, first level. Using styles, rather than direct formatting has the following advantages:

  • Gives your pages, paragraphs, texts, and lists a consistent look.

  • Makes it easy to consistently change formatting later.

  • Allows reuse and import of styles from another document.

  • Change one style and its properties are passed on to its descendants.

Example 11.1: Use of Styles

Imagine that you emphasize text by selecting it and clicking the button Bold. Later, you decide you want the emphasized text to be italicized. Now, without styles, you need to find all bold text and manually change it to italics.

If you had used a character style from the beginning, however, you would only need to change the style from bold to italics once. All text formatted with a style changes its appearance as the style is changed.

LibreOffice can use styles for applying consistent formatting to various elements in a document. The following types of styles are available in Writer:

Table 11.1: Types of Styles

Type of Style

Function

Paragraph

Applies standardized formatting to the various types of paragraphs in your document. For example, apply a paragraph style to a first-level heading to set the font and font size, spacing above and below the heading, location of the heading, and other formatting specifications.

Character

Applies standardized formatting for types of text. For example, if you want emphasized text to appear in italics, you can create an emphasis style that italicizes selected text when you apply the style to it.

Frame

Applies standardized formatting to frames. For example, if your document uses marginal notes, you can create frames with specified borders, location, and other formatting, so that all of your marginal notes have a consistent appearance.

Frames are also used for captioning images: A frame can keep the caption and the image together. Here, you can use frame style to make sure that all your images have the same size and background color, for example.

Page

Applies standardized formatting to a specified type of page. For example, if every page of your document contains a header and footer except for the first page, you can use a first page style that disables headers and footers. You can also use different page styles for left and right pages so that you have bigger margins on the insides of pages and your page numbers appear on an outside corner.

List

Applies standardized formatting to specified list types. For example, you can define a checklist with square check boxes and a bullet list with round bullets, then easily apply the correct style when creating your lists.

Direct formatting overrides any styles you have applied. For example, format a piece of text both with a character style and using the button Bold. Now, the text will be bold, no matter what is set in the style.

To remove all direct formatting, first select the appropriate text, then right-click it and choose Clear Direct Formatting.

Likewise, if you manually format paragraphs using Format › Paragraph, you can end up with inconsistent paragraph formatting. This is especially true if you copy and paste paragraphs from other documents with different formatting. However, if you apply paragraph styles, formatting remains consistent. If you change a style, the change is automatically applied to all paragraphs formatted with that style.

11.2.1 The Side Bar Panel Styles and Formatting

The side bar panel Styles and Formatting is a versatile formatting tool for applying styles to text, paragraphs, pages, frames, and lists. To open this panel, click Styles › Styles and Formatting, click the button Styles and Formatting (a T) in the side bar or press F11.

Styles and Formatting Panel
Figure 11.2: Styles and Formatting Panel

LibreOffice comes with several predefined styles. You can use these styles as they are, modify them, or create new styles. Use the icons at the top of the panel to display formatting styles for the most common elements such as paragraphs, frames, pages or lists. To learn more about styles, continue with the instructions below.

11.2.2 Applying a Style

To apply a style, select the element you want to apply the style to, and double-click the style in the panel Styles and Formatting. For example, to apply a style to a paragraph, place the cursor anywhere in that paragraph and double-click the desired paragraph style.

Alternatively, use the paragraph style selector in the toolbar Formatting.

11.2.3 Changing a Style

By changing styles, you can change formatting throughout a document, rather than applying the change separately everywhere you want to apply the new formatting.

To change an existing style, proceed as follows:

  1. In the panel Styles and Formatting, right-click the style you want to change.

  2. Click Modify.

  3. Change the settings for the selected style.

    For information about the available settings, refer to the LibreOffice online help.

  4. Click OK or Apply.

11.2.4 Creating a Style

LibreOffice comes with a collection of styles to suit many needs of most users. However, if you need a style that does not yet exist and want to create your own style, follow the procedure below:

Procedure 11.1: Creating a New Style
  1. Open the panel Styles and Formatting with Styles › Styles and Formatting, or pressing F11.

  2. Make sure you are in the list of styles for the type of style you want to create.

    For example, if you are creating a character style, make sure you are in the character style list by clicking the corresponding icon in the panel Styles and Formatting.

  3. Right-click anywhere in the list of styles in the panel Styles and Formatting.

  4. To open the style dialog, click New. The Organizer tab is preselected.

  5. Configure three basic properties of the new style:

    Name

    The name of your style. Choose any name you like.

    Next Style

    The style that follows your style. The style selected here is used when starting a new paragraph by pressing Enter. This is useful, for example, for headlines, after which you usually want to start a normal paragraph of text.

    Inherit From

    A style that your style depends on. If the selected style is changed, your style changes as well. For example, to make headers consistent, create a parent header style and have subsequent headers depend on it. This is useful when you only want to change the properties that need to be different.

    For details about the style options available in any tab, click the Help button of the dialog.

  6. Confirm with OK. This closes the window.

11.2.4.1 Example: Defining a Note Style

Let us assume, you need a note with a different background and borders. To create such a style, proceed as follows:

Procedure 11.2: Creating a Note Style
  1. Press F11. The panel Styles and Formatting opens.

  2. Make sure you are in the Paragraph Style list by checking that the pilcrow icon (¶) is selected.

  3. Right-click anywhere in the list of styles in the panel Styles and Formatting and select New.

  4. Specify the following parameters in the tab Organizer:

    Name

    Note

    Next Style

    Note

    Inherit from

    - None -

    Category

    Custom Styles

  5. Change the indentation in the tab Indents & Spacing, using the text field Before Text. If you also want more space above and below individual paragraphs, change the values in the Above paragraph and Below paragraph accordingly.

  6. Switch to the tab Background and choose a color for the background.

  7. Switch to the tab Borders and determine your line arrangements, line style, color and other parameters.

  8. Confirm with OK. This closes the window.

  9. Select your text in your document and double-click the style Note. Your style parameters are applied to the text.

11.2.4.2 Example: Defining an Even-Odd Page Style

If you want to create double-sided printouts of your documents, especially if they are supposed to be bound, use templates for even and odd pages. To create page styles for this, proceed as follows:

Procedure 11.3: Create an Even (Left) Page Style
  1. Press F11. The panel Styles and Formatting opens.

  2. Make sure you are in the list Page Style by checking that the paper sheet icon is selected.

  3. Right-click anywhere in the list of styles in the panel Styles and Formatting and select New.

  4. Enter the following parameters in the tab Organizer:

    Name

    Left Content Page

    Next Style

    Leave empty, will be changed later

    Inherit from

    not applicable

    Category

    not applicable

  5. Change additional parameters as you like in the other tabs. You can also adapt the page format and margins (tab Page) or any headers and footers.

  6. Confirm with OK. This closes the window.

Procedure 11.4: Create an Odd (Right) Page Style
  1. Follow the instruction in Procedure 11.3, “Create an Even (Left) Page Style” but use the string Right Content Page in the Organizer tab.

  2. Select the entry Left Content Page from the drop-down box Next Style.

  3. Choose the same parameters as you did for the left page style. If you used different sizes for the left and right margin of your even page, mirror these values in your odd pages.

  4. Confirm with OK. This closes the window.

Then connect the left page style with the right page style:

Procedure 11.5: Connect the Right Page Style with the Left Page Style
  1. Right-click the entry Left Content Page and choose Modify.

  2. Choose Right Content Page from the drop-down box Next Style.

  3. Confirm with OK. This closes the window.

To attach your style, make sure your page is a left (even) page and double-click Left Content Page. Whenever your text exceeds the length of a page, the following page automatically receives the alternative page style.

11.3 Working with Large Documents

You can use Writer to work on large documents. Large documents can be either a single file or a collection of files assembled into a single document.

11.3.1 Navigating in Large Documents

The Navigator tool displays information about the contents of a document. It also lets you quickly jump to different elements. For example, use the Navigator to get a quick overview of all images included in a document.

To open the Navigator, click View › Navigator or press F5. The elements listed in the Navigator vary with the document loaded in Writer.

The Navigator is also an element of the side bar: There, it can be opened using the button Navigator (a compass).

Double-click an item in the Navigator to jump to that item in the document.

Navigator Tool in Writer
Figure 11.3: Navigator Tool in Writer

11.3.2 Using Master Documents

If you are working with a very large document, such as a book, it can be easier to manage the book with a master document, rather than keeping the book in a single file. A master document enables you to quickly apply formatting changes to a large document or to jump to each subdocument for editing.

A master document is a Writer document that serves as a container for multiple Writer files. You can maintain chapters or other subdocuments as individual files collected in the master document. Master documents are also useful if multiple users are working on a single document. You can separate each user’s section of the document into subdocuments collected in a master document, allowing multiple writers to work on their subdocuments at the same time without fear of overwriting the work of others.

Procedure 11.6: Creating a Master Document
  1. Click New › Master Document.

    or

    Open an existing document and click File › Send › Create Master Document.

  2. The Navigator window will open. In it, select Insert (Insert), then choose File.

  3. Select a file to add an existing file to the master document.

Procedure 11.7: Adding a New Document to a Master Document
  1. In the window or panel Navigator, choose Insert (Insert), then select New Document.

  2. A file chooser opens, to allow saving the new document. Specify a name, then click Save.

  3. When you are done editing the new document, save it. Then switch back to the master document.

  4. Update the master document with the contents of the new document. To do so, right-click the entry of your new document in the Navigator, then click Update › Selection.

To enter some text directly into the master document, select Insert › Text.

The LibreOffice help files contain more complete information about working with master documents. Look for the topic named Using Master Documents and Subdocuments.

Tip
Tip: Styles and Templates in Master Documents

The styles from all of your subdocuments are imported into the master document. To ensure that formatting is consistent throughout your master document, use the same template for each subdocument. Doing so is not mandatory.

However, if subdocuments are formatted differently, you might need to do some reformatting to successfully bring subdocuments into the master document without creating inconsistencies. For example, if two documents within a master document include styles with the same name, the master document will use the formatting specified for the style in the document imported first.

11.4 Using Writer as an HTML Editor

In addition to being a full-featured word processor, Writer also functions as an HTML editor. You can style HTML pages like any other document, but there are specific HTML Styles that help with creating good HTML. You can view the document as it will appear online, or you can directly edit the HTML code.

Procedure 11.8: Creating an HTML Page
  1. Click File › New › HTML Document.

  2. Press F11 to open the panel Styles and Formatting.

  3. At the bottom of the panel Styles and Formatting, click the drop-down box to open it.

  4. Select HTML Styles.

  5. Create your HTML page, using the styles to tag your text.

  6. Click File › Save As.

  7. Select the location where you want to save your file and name the file. Make sure that in the bottom drop-down box, HTML Document is selected.

  8. Click OK.

To edit HTML code directly or to see the HTML code created when you edit the HTML file as a Writer document, click View › HTML Source. In HTML Source mode, the Formatting and Styles list is not available.

The first time you switch to HTML Source mode, you are prompted to save the file as HTML, if you have not already done so.

To switch back from HTML Source mode to Web Layout, click View › HTML source again.

12 LibreOffice Calc

  • Filename: apps_librecalc.xml
  • ID: cha.oo.calc

Calc is the LibreOffice spreadsheet module. Spreadsheets consist of several sheets, containing cells which can be filled with elements like text, numbers, or formulas. A formula can manipulate data from other cells to generate a value for the cell in which it is inserted. Calc also allows you to define ranges, filter and sort data and creates charts from data to present it graphically. Using pivot tables, you can combine, analyze or compare larger amounts of data.

This chapter can only introduce some very basic Calc functionality. For more information and for complete instructions, see the LibreOffice application help and the sources listed in Section 10.10, “For More Information”.

Note
Note: VBA Macros

Calc can process many VBA macros in Excel documents. However, support for VBA macros is not complete. When opening an Excel spreadsheet that makes heavy use of macros, you might discover that some do not work.

12.1 Creating a New Document

There are two ways to create a new Calc document:

  • From Scratch.  To create a new empty document, click File › New › Spreadsheet.

  • From a Template.  To use a template, click File › New › Templates and open, for example, Finances. From the list of spreadsheet templates, select the one that fits your needs.

Access the individual sheets by clicking their respective tabs at the bottom of the window.

Enter data in the cells as desired. To adjust the appearance, either use the Formatting toolbar or side bar panel, or use the Format menu—or define styles as described in Section 12.2, “Using Formatting and Styles in Calc”. Use the File menu or the relevant buttons in the toolbar to print and save your document.

12.2 Using Formatting and Styles in Calc

Calc comes with a few built-in cell and page styles to improve the appearance of your spreadsheets and reports. Although these built-in styles are adequate for many uses, you will probably find it useful to create styles for your own frequently used formatting preferences.

Procedure 12.1: Creating a Style
  1. Click Format › Styles › Styles and Formatting or press F11.

  2. At the top of the panel Styles and Formatting, click either Cell Styles (a green cell) or Page Styles (a document).

  3. Right-click anywhere in the list of styles in the panel Styles and Formatting. Then click New.

  4. Specify a name for the style and use the various tabs to set the desired formatting options.

  5. When you are done configuring the style, click OK.

Procedure 12.2: Modifying a Style
  1. Click Format › Styles › Styles and Formatting.

  2. At the top of the panel Styles and Formatting, click either Cell Styles (a green cell) or Page Styles (a document).

  3. Right-click the name of the style you want to change, then click Modify.

  4. Change the desired formatting options.

  5. When you are done configuring the style, click OK.

To apply a style to specific cells, select the cells you want to format. Then double-click the style you want to apply in the Styles and Formatting window.

12.3 Working With Sheets

Sheets are a good method to organize your calculations. For example, if you have a business, accounting might be much clearer if you create a sheet for each month.

To insert a new sheet after the last sheet, click the button + next to the sheet tabs.

To insert one or more new sheets into your spreadsheet from a file or at a specific position at once, do the following:

Procedure 12.3: Inserting New Sheets
  1. Right-click a sheet tab and select Insert Sheet. A dialog opens.

  2. Decide whether the new sheet should be positioned before or after the selected sheet.

  3. To create a new sheet, make sure the New Sheet radio button is activated. Enter the number of sheets and the sheet name. Skip the rest of this step.

    Alternatively, to import a sheet from another file, do the following:

    1. Select From file and click Browse.

    2. Select the file name and confirm with OK. All the sheet names are now displayed in the list.

    3. Select the sheet names you want to import by holding the Shift key and clicking them.

  4. To add the sheet or sheets, confirm with OK.

To rename a sheet, right-click the tab of the sheet and select Rename Sheet. Alternatively, you can also double-click the sheet tab.

To delete one or multiple sheets, do the following: Select the sheet you want to delete. To select more than one sheet, hold down Shift while making the selection. Then right-click the tab of the sheet, choose Delete Sheet and confirm with Yes.

12.4 Conditional Formatting

Conditional formatting is a useful feature to highlight certain values in your spreadsheet. For example, define a condition and if the condition is true, a style is applied to each cell that fulfills this condition.

Note
Note: Enable AutoCalculate

Before you apply conditional formatting, choose Tools › Cell Contents › AutoCalculate. You should see a check mark in front of AutoCalculate.

Procedure 12.4: Using Conditional Formatting
  1. Define a style first. This style is applied to each cell when your condition is true. Use Format › Styles and Formatting or press F11. For more information, see Procedure 12.1, “Creating a Style”. Confirm with OK.

  2. Select the cell range where you want to apply your condition.

  3. Select Format › Conditional Formatting › Condition from the menu. A dialog opens.

  4. You now see a template for a new condition. Conditions can operate in multiple modes:

    Cell value is

    The condition tests if a cell matches a certain value. Next to the first drop-down box, select an operator such as equal to, less than, or greater than.

    Formula is

    The condition tests if a certain formula returns true.

    Date is

    The condition tests if a certain date value is reached.

    All Cells

    This mode allows creating data visualizations that depend on the value of a cell, similarly to Cell value is. However, with All Cells, you can use one condition to apply an entire range of styles.

    The types of styles that can be used are color scales (cell background color), data bars (bars with changing width in the cell) and icon sets (an icon in the cell).

    For example, a color scale allows assigning 0 a black background and 100 a green background. All values in between are calculated automatically. For example, 50 receives a dark green background.

  5. For this example, keep the default: Cell value is.

  6. Select an operator and the value of the cell you want to test for.

  7. Choose the style you want to apply when this condition is true or click New Style to define a new appearance.

  8. If you need additional conditions, click Add. Then repeat the previous steps.

  9. Confirm with OK. Now the style of your cells has changed.

12.5 Grouping and Ungrouping Cells

Grouping a cell range allows hiding parts of a spreadsheet. This makes spreadsheets more readable, as you can hide all the parts you are not currently interested in. It is possible to group rows or columns and nest groups in other groups.

To group a range, proceed as follows:

Procedure 12.5: Grouping a Selected Cell Range
  1. Select a cell range in your spreadsheet.

  2. Select Data › Group and Outline › Group. A dialog appears.

  3. Decide if you want to group your selected range by rows or by columns. Confirm with OK.

After grouping selected cells, a line indicating the grouped cell range appears in the upper-left margin. Fold or unfold the cell range with the + and icons. The numbers at the top left of the margins display the depth of your groups and can be clicked too.

To ungroup a cell range, click into a cell which belongs to a group and select Data › Group and Outline › Ungroup. The line in the margin disappears. The innermost group is always deleted first.

12.6 Freezing Rows or Columns as Headers

If you have a spreadsheet with lots of data, scrolling usually makes the header disappear. LibreOffice can lock rows or columns or both, so they remain fixed as you scroll around.

To freeze a single row or a single column, proceed as follows:

Procedure 12.6: Freezing a Single Row or Column
  1. To create a frozen area before a row, click the header of the row (1, 2, 3, ...).

    Alternatively, to create a frozen area above a column, click the header of the column (A, B, C, ...).

  2. Select View › Freeze Rows and Columns. A dark line appears, indicating the frozen area.

It is also possible to freeze both rows and columns:

Procedure 12.7: Freezing Row and Column
  1. Click into the cell to the right of the column and below the row you want frozen. For example, if your header occupies the space from A1 to B3, click cell C4.

  2. Select View › Freeze Rows and Columns. A dark line appears, indicating which area is frozen.

To unfreeze, select View › Freeze Rows and Columns. The check mark before the menu item disappears.

13 LibreOffice Impress, Base, Draw, and Math

  • Filename: apps_librevarious.xml
  • ID: cha.oo.various

Besides LibreOffice Writer and LibreOffice Calc, LibreOffice also includes the modules Impress, Base, Draw, and Math. With these you can create presentations, design databases, draw up graphics and diagrams, and create mathematical formulas.

13.1 Using Presentations with Impress

Use LibreOffice Impress to create presentations for screen display or printing. If you have used other presentation software, Impress makes it easy to switch. It works very similarly to other presentation software.

13.1.1 Creating a Presentation

There are multiple ways to create a new Impress document:

  • From Scratch.  To create a new empty document, click File › New › Presentation.

  • Using a Wizard.  To use a standard format and predefined elements for your documents use a wizard. Click File › Wizards › Presentation and follow the steps.

  • From a Template.  To use a template, click File › New › Templates and open, for example, Presentation Backgrounds. From the list of presentation templates, select the one that fits your needs.

The following procedure describes how to create a presentation by using the wizard. Proceed as follows:

Procedure 13.1: Creating a Presentation Using the Wizard
  1. Start LibreOffice.

  2. Select File › Wizards › Presentation.

  3. Choose From template. Select Presentation Backgrounds from the pop-up menu to set your preferred background and click Next.

  4. Select an output medium. The output medium is the form the final presentation will take, such as: Overhead sheet, Paper, a slideshow on a 4:3 Screen or a 16:9 Widescreen, among other choices.

    To see a thumbnail showing your choices, make sure Preview is activated. If all options are set according to your wishes, click Next.

  5. To use effects for slide transitions, select an Effect and its Speed. The effect will be previewed immediately.

  6. Either use the default presentation type or choose Automatic to specify the amount of time each page displays and the length of the pause between presentations.

  7. If all options are set according to your wishes, click Create.

The presentation opens, ready for editing.

13.1.2 Using Master Pages

Master pages give your presentation a consistent look by defining what fonts and other design elements are used. Impress uses two types of master pages:

Slide Master

Contains elements that appear on all slides. For example, you might want your company logo to appear in the same place on every slide. The slide master also determines the text formatting style for the heading and outline of every slide that uses that master page, as well as any information you want to appear in a header or footer.

Notes Master

Determines the formatting and appearance of the notes in your presentation.

13.1.2.1 Creating a Slide Master

Impress comes with a collection of preformatted master pages. To customize presentations further, create your own slide masters.

  1. Start Impress with an existing presentation or create a new one as described in Section 13.1.1, “Creating a Presentation”.

  2. Click View › Slide Master.

    This opens the current slide master in Master View. The Master View toolbar appears.

  3. Right-click the left-hand panel, then click New Master.

  4. Edit the slide master until it has the desired look.

    Master view allows editing outline styles by directly formatting the sample text on the slide.

  5. To finish editing slide masters, in the Master View toolbar, click Close Master View. Alternatively, choose View › Normal.

Tip
Tip: Collect Slide Masters in a Template

When you have created all of the slide masters you want to use in your presentations, you can save them in an Impress template. Then, any time you want to create presentations that use those slide masters, open a new presentation with your template.

13.1.2.2 Applying a Slide Master

Slide masters can be applied to selected slides or to all slides of a presentation.

  1. Open your presentation.

  2. (Optional) To apply a slide master to multiple slides but not all slides: Select the slides that you want a slide master applied to.

    To select multiple slides, pressCtrl in the Slides Pane while clicking the slides you want to use.

  3. In the Tasks pane, open the Master Pages and click the master page you want to apply. The slide master is applied to the corresponding page or pages.

    If you do not see the Task Pane, click View › Task Pane.

13.2 Using Databases with Base

LibreOffice includes the database module Base. Use Base to design a database to store many kinds of information. From a simple address book or recipe file to a sophisticated document management system.

Tables, forms, queries, and reports can be created manually or by using convenient wizards. For example, the Table Wizard contains several common fields for business and personal use. Databases created in Base can be used as data sources, such as when creating form letters.

It is beyond the scope of this document to detail database design with Base. Find more information at the sources listed in Section 10.10, “For More Information”.

13.2.1 Creating a Database Using Predefined Options

Base comes with several predefined database fields to help you create a database. A wizard guides you through the steps to create a new database. The steps in this section are specific to creating an address book using predefined fields, but it should be easy to follow them to use the predefined fields for any of the built-in database options.

The process for creating a database can be broken into several subprocesses:

13.2.1.1 Creating the Database

  1. Start LibreOffice Base.

    The Database Wizard starts.

    You can choose between creating an HSQLDB or Firebird database.

    HSQLDB Embedded (default)

    This database format is also available in older versions of OpenOffice.org and LibreOffice. It depends on Java being installed on the computer.

    Firebird Embedded

    This database format can only be used in newer versions of LibreOffice. It does not depend on Java. When you do large database operations, Firebird can perform better.

  2. Proceed with Next.

  3. Click Yes, register the database for me to make your database information available to other LibreOffice modules and select the check boxes to Open the database for editing and Create tables using the table wizard. Then click Finish.

  4. Browse to the directory where you want to save the database, specify a name for the database, then click Save.

13.2.1.2 Setting Up the Database Table

After you have created the database, if you have selected the Create tables using the table wizard check box, the table wizard opens. If you have not, go to the Task area and click Use Wizard to Create Table. Next, define the fields you want to use in your database table.

In this example, set up an address database.

  1. For this example, click Personal.

    The list Sample tables changes to show the predefined tables for personal use where the address table template is. The table templates listed under Business contain predefined business tables.

  2. In the Sample tables list, click Addresses.

    The available fields for the predefined address book appear in the Available fields menu.

  3. In the Available fields menu, click the fields you want to use in your address book.

    Select one item at a time by clicking. Alternatively, to select multiple items, hold Shift and click each of the items separately.

  4. Click the icons single right arrow and single left arrow to move selected items to or off the Selected fields list.

    To move all available fields to the Selected fields menu, click the icon double right arrow.

  5. Use the icons up arrow and down arrow to adjust the order of the selected entries, then click Next.

    The fields appear in the table and forms in the order in which they are listed.

  6. Make sure each of the fields is defined correctly.

    You can change the field name, type, maximum characters and whether it is a required field. For this example, leave the settings as they are, then click Next.

  7. Make sure that Create a primary key and Automatically add a primary key are activated. Additionally activate Auto value.

    Proceed with Next.

  8. Give the table a name, and activate Create a form based on this table.

    Proceed with Finish.

13.2.1.3 Creating a Form

Next, create the form to use when entering data into your address book.

After the previous step, you should be in the Form Wizard already. Otherwise, open it by going to the main window. Under Tables, right-click the correct table. Click Form Wizard.

  1. In the Form Wizard, click the double right-arrow icon to move all available fields to the Fields in the form list, then click Next.

  2. To add a subform, activate Add Subform, then click Next.

    For this example, accept the default selections.

  3. Select how you want to arrange your form, then click Next.

  4. Select The form is to display all data and leave all of the check boxes deactivated, then click Next.

  5. Apply a style and field border, then click Next.

    For this example, accept the default selections.

  6. Name the form, activate Modify the form, then click Finish.

13.2.1.4 Modifying the Form

After the form has been defined, you can modify the appearance of the form to suit your preferences.

After the previous step, you should be in the Database Form editor already. If not, select the right form by clicking Forms in the side bar of the main window. Then, in the Forms area, right-click the correct form. Select Edit.

  1. Arrange the fields on the form by dragging them to their new locations.

    For example, move the field First Name, so it appears to the right of the field Last Name.

  2. When you have finished modifying the form, save it and close it.

13.2.1.5 Further Steps

After you have created your database tables and forms, you are ready to enter your data. You can also design queries and reports to help sort and display the data.

Refer to LibreOffice online help and other sources listed in Section 10.10, “For More Information” for additional information about Base.

13.3 Creating Graphics with Draw

Use LibreOffice Draw to create graphics and diagrams. You can export your drawings to the most common vector graphics formats and import them into any application that lets you import graphics, including other LibreOffice modules. You can also create Adobe* Flash* (SWF) versions of your drawings.

Procedure 13.2: Creating a Graphic
  1. Start LibreOffice Draw.

  2. Use the toolbar Drawing at the right side of the window to create a graphic. To create a new shape or text object, use the shape buttons of the toolbar:

    • To create a single shape or text object, click a shape button once. Then click and drag over the document to create an object.

    • To create a multiple shape or text object, double-click a shape button. Then click and drag over the document to create objects. When you are done, click the mouse pointer icon in the toolbar.

  3. Save the graphic.

To embed an existing Draw graphic into a LibreOffice document, select Insert › Object › OLE Object. Select Create from file and click Search to navigate to the Draw file to insert.

To be able to edit the graphic later on its own, activate Link to file.

If you insert a file as OLE object, you can edit the object later by double-clicking it.

Procedure 13.3: Opening Draw From Other LibreOffice Modules

One particularly useful feature of Draw is the ability to open it from other LibreOffice modules, so you can create a drawing that is automatically imported into your document.

  1. From a LibreOffice module (for example, from Writer), click Insert › Object › OLE Object › LibreOffice Drawing › OK.

    The user interface of Writer will now be replaced by that of Draw.

  2. Create your drawing.

  3. Click in your document, outside the Draw frame.

    The drawing is automatically inserted into your document.

13.4 Creating Mathematical Formulas with Math

It is usually difficult to include complex mathematical formulas in your documents. To make this task easier, the LibreOffice Math equation editor lets you create formulas using operators, functions, and formatting assistants. You can then save those formulas as an object that can be imported into other documents. Math functions can be inserted into other LibreOffice documents like any other graphic object.

Note
Note: Math is For Creating Mathematical Formulas

Math is not a calculator. The functions it creates are graphical objects. Even if they are imported into Calc, these functions cannot be evaluated.

To create a formula, proceed as follows:

  1. Start LibreOffice Math.

  2. Click File › New › Formula. The formula window opens.

  3. Enter your formula in the lower part of the window. For example, the binomial theorem in LibreOffice Math syntax is:

    (a + b)^2 = a^2 + 2 a b + b^2

    The result is displayed in the upper part of the window.

  4. Use the side bar panel Formula Elements or right-click the lower part of the window to insert other terms. If you need symbols, use Tools › Symbols to, for example, insert Greek or other special characters.

  5. Save the document.

The result is shown in Figure 13.1, “Mathematical Formula in LibreOffice Math”:

Mathematical Formula in LibreOffice Math
Figure 13.1: Mathematical Formula in LibreOffice Math

It is possible to include your formula in Writer, for example. To do so, proceed as follows:

  1. Create a new Writer document or open an already existing one.

  2. Select Insert › Object › OLE Object in the main menu. The Insert OLE Object window appears.

  3. Select Create from file.

  4. Click Search to locate your formula. To choose the formula file, click Open.

    To be able to edit the formula later on its own, activate Link to file.

  5. Confirm with OK. The formula is inserted at the current cursor position.

Part IV Internet, Communication and Collaboration

14 Firefox: Browsing the Web

The Mozilla Firefox Web browser is included with SUSE® Linux Enterprise Server. With features like tabbed browsing, pop-up window blocking and download management, Firefox combines the latest browsing and security technologies with an easy-to-use interface. Firefox gives you easy access to different search engines to help you find the information you need.

15 Evolution: E-Mailing and Calendaring

Evolution makes storing, organizing, and retrieving your personal information easy, so you can work and communicate more effectively with others. It is a professional groupware program and an important part of the Internet-connected desktop.

16 Empathy: Instant Messaging

Empathy is an instant messaging (IM) client that allows you to connect to multiple accounts simultaneously. Chat live with your contacts in one tabbed interface, regardless of which IM system they use. Empathy uses Telepathy for protocol support.

17 Ekiga: Using Voice over IP

Ekiga is an application you can use for making phone calls via Voice over IP (VoIP), for video conferencing and for instant messaging.

14 Firefox: Browsing the Web

  • Filename: apps_firefox.xml
  • ID: cha.firefox
Abstract

The Mozilla Firefox Web browser is included with SUSE® Linux Enterprise Server. With features like tabbed browsing, pop-up window blocking and download management, Firefox combines the latest browsing and security technologies with an easy-to-use interface. Firefox gives you easy access to different search engines to help you find the information you need.

14.1 Starting Firefox

To start Firefox, select Applications › Internet › Firefox.

14.2 Navigating Web Sites

The look and feel of Firefox is similar to that of other browsers. It is shown in Figure 14.1, “The Browser Window of Firefox”. At the top of the window you find the location bar for a Web address, and the search bar. Bookmarks are also available for quick access from the bookmarks toolbar. For more information about the various Firefox features, use the Help menu in the menu bar.

Note
Note: Using the Menu Bar

While most functions of Firefox are available through the three-lines button (Three-lines button), some are only available from the menu bar.

The menu bar of Firefox is hidden by default. To temporarily show it, press Alt. It will then be displayed until you click elsewhere in the Firefox window.

To permanently enable the Firefox menu bar, first press Alt, then choose View › Toolbars and activate Menu Bar.

The Browser Window of Firefox
Figure 14.1: The Browser Window of Firefox

14.2.1 The Location Bar

When typing into the location bar, an auto-completion drop-down box opens. It shows all previous location addresses and bookmarks containing the characters you type. The matching phrase is highlighted in bold. Entries visited most frequently and recently are listed first.

List entries from the bookmark list are marked with a star. Bookmarks with tags are marked with an additional label followed by the tag names. List entries from the browsing history are not marked. To search in your bookmarks only, type * as the first character of your search.

Use and or the mouse wheel to navigate the list. Press Enter or click an entry to go to the selected page. Del removes an entry from the list if it is an entry from the history. Bookmarked entries can only be removed by deleting the associated bookmark.

14.2.2 Zooming

Firefox offers two zooming options: page zoom, the default, and text zoom. Page zoom enlarges the entire page as is, with all elements of a page, including graphics, expanding equally while text zoom only changes the text size.

To toggle between page and text zoom, from the menu bar, choose View › Zoom › Zoom Text Only. To zoom in or out either use the mouse wheel while holding the Ctrl key, or use Ctrl+ and Ctrl-. Reset the zoom factor with Ctrl0.

14.2.3 Tabbed Browsing

Tabbed browsing allows you to load multiple Web sites in a single window. To switch between pages in use, use the tabs at the top of the window. If you often use more than one Web page at a time, tabbed browsing makes it easier to switch between pages.

Opening Tabs

To open a new tab, from the menu bar, select File › New Tab or press CtrlT. This opens an empty tab in the Firefox window. To open a link on a Web page or a bookmark in a tab, middle-click it. Alternatively, right-click a link and select Open Link in New Tab. You may also open an address in the location bar in a new tab with a middle-click or by pressing CtrlEnter.

Closing Tabs

Right-click a tab to open a context menu, giving you access to tab managing options such as closing, reloading, or bookmarking. To close a tab, you may also use CtrlW or click the close button. Any closed tab can be restored by choosing from the menu bar, History › Recently Closed Tabs. To reopen the last closed tab, either choose Undo Close Tab from the context menu or press CtrlShiftT.

Sorting Tabs

By default, tabs are sorted in the order you opened them. Rearrange the tab order by dragging and dropping a tab to the desired position. If you have opened a large number of tabs, they cannot all be displayed in the tab bar at the same time. Use the arrows at the ends of the bar to move left or right-click the down arrow at the right end of the tab bar to get a list of all tabs.

Dragging and Dropping

Drag and drop also works with tabs. Drag a link onto an existing tab to open it in that tab or drag and drop a link on an empty space in the tab bar to open a new tab. Drag and drop a tab outside of the tab bar to open it in a new browser window.

14.2.4 Using the Sidebar

Use the left side of your browser window for viewing bookmarks or browsing history. Extensions may add new ways to use the sidebar as well. To display the sidebar, from the menu bar, select View › Sidebar and select the desired contents.

14.3 Finding Information

There are two ways to find information in Firefox: to search the Internet with a search engine, use the search bar. To search the page currently displayed, use the find bar.

14.3.1 Finding Information on the Web

Firefox has a search bar that can access different engines like Google, Yahoo, or Amazon. For example, if you want to find information about SUSE using the current engine, click in the search bar, type SUSE, and press Enter. The results appear in your window.

To choose a different search engine, type your search term, then click one of the search provider icons at the bottom of the appearing pop-up.

14.3.1.1 Customizing the Search Bar

If you want to change the order, add, or delete a search engine, proceed as follows.

  1. Click the icon to the left of the search bar.

  2. From the pop-up, select Change Search Settings. The Search dialog shows the engine that is currently set as default search engine and other available search engines.

  3. To change the order of entries, use the mouse to drag them.

    To delete an entry, select it and click Remove.

    To add a search engine, click Add More Search Engines. Firefox displays a Web page with available search plug-ins. To install a search plug-in, select it and click Add to Firefox.

Some Web sites offer search engines that you can add directly to the search bar. Whenever you are visiting such a Web site, the icon to the left of the search bar gains a + sign. Click the icon and select Add.

14.3.1.2 Adding Keywords to Your Online Searches

Firefox lets you define own keywords: abbreviations to use as a URL shortcut for a particular search engine. If you have defined ws as a keyword for the Wikipedia search for example, you can type ws SEARCHTERM into the location bar to search Wikipedia for SEARCHTERM.

To assign a shortcut for a search engine from the search bar, click the icon to the left of the search bar and select Change Search Settings. Select a search engine, double-click its Keyword column, enter a keyword and press Enter.

It is also possible to define a keyword for any search field on a Web site. Proceed as follows:

  1. Right-click the search field and choose Add a Keyword for this Search from the menu that opens. The Add Bookmark dialog appears.

  2. In Name, enter a descriptive name for this keyword.

  3. Enter your Keyword for this search.

  4. Save this keyword.

Tip
Tip: Keywords for Regular Web Sites

Using keywords is not restricted to search engines. You can also add a keyword to a bookmark (via the bookmark's properties). For example, if you assign suse to the SUSE home page bookmark, you can open it by typing suse into the location bar.

14.3.2 Searching in the Current Page

To search inside a Web page, in the menu bar, click Edit › Find or press CtrlF. The find bar opens. It is usually displayed at the bottom of a window. Type your query in the text box. Firefox finds the first occurrence of this phrase as you type. You can find other occurrences of the phrase by pressing F3 or the Next button in the find bar. Clicking the Highlight All button will highlight all occurrences of the phrase. Checking the Match Case option makes the query case-sensitive.

Firefox also offers two quick-find options. Click anywhere you like to start a search on a Web page, type the key / immediately followed by the search term. The first occurrence of the search term will be highlighted as you type. Use F3 to find the next occurrence. It is also possible to limit quick-find to links only. This search option is available by typing the key '.

14.4 Managing Bookmarks

Bookmarks offer a convenient way of saving links to your favorite Web sites. Firefox not only makes it very easy to add new bookmarks with just one mouse click, it also offers multiple ways to manage large bookmark collections. You can sort bookmarks into folders, classify them with tags, or filter them with smart bookmark folders.

Add a bookmark by clicking the star in the location bar. The star will turn blue to indicate the page was bookmarked. The bookmark will be saved in the Unsorted Bookmarks folder under the page title. To change the name and folder of your bookmark or add tags, after bookmarking, click the star again. This will open a pop-up where you can make your changes.

To bookmark all open tabs, right-click in a tab and choose Bookmark All Tabs. Firefox asks you to create a new folder for the tab links.

To remove a bookmark, open the bookmarked location. Then, click the star and click Remove Bookmark.

14.4.1 Organizing Bookmarks

The Library can be used to manage the properties (name and address location) for each bookmark and organize the bookmarks into folders and sections. It resembles Figure 14.3, “The Firefox Bookmark Library”.

The Firefox Bookmark Library
Figure 14.3: The Firefox Bookmark Library

To open the Library, in the menu bar, click Bookmarks › Show All Bookmarks. The library window is split into two parts: the left pane shows the folder tree view, the right pane the subfolders and bookmarks of the selected folder. Use Views to customize the right pane. The left pane contains three main folders:

History

Contains your complete browsing history. You cannot alter this list other than by deleting entries from it.

Tags

Lists bookmarks for each tag you have specified. See Section 14.4.2, “Tags” for more information on tags.

All Bookmarks

This category contains the three main bookmark folders:

Bookmarks Toolbar

Contains the bookmarks and folders displayed beneath the location bar. See Section 14.4.6, “The Bookmarks Toolbar” for more information.

Bookmarks Menu

Holds the bookmarks and folder accessible via the Bookmarks entry in the main menu or the bookmarks side menu.

Unsorted Bookmarks

Contains all bookmarks created with a single click the star in the location bar. This folder is only visible in the library and the bookmarks sidebar.

Organize your bookmarks using the right pane. Choose actions for folders or bookmarks either from the context menu that opens when you right-click an item or from the Organize menu. The properties of a chosen folder or bookmark can be edited in the bottom part of the right pane. By default, only Name, Location, and Tags are displayed for a bookmark. Click the arrow next to More to gain access to all properties.

To rearrange your bookmarks, use the mouse to drag them. You can use this to move a bookmark or a folder to a different folder, or to change the order of bookmarks in a folder.

14.4.2 Tags

Tags offer a convenient way to file a bookmark under several categories. You can tag a bookmark with as many terms as you want. For example, to access all sites tagged with suse, enter suse into the location bar. For each tag, an item is automatically created in the Recent Tags folder of the library. Drag and drop an item for a tag onto the bookmark toolbar to easily access it.

To add tags to a bookmark, open the bookmark in Firefox and click the yellow star in the location bar. The Edit This Bookmark dialog opens where you can add a comma separated list of tags. It is also possible to add tags via the bookmark's properties dialog which you can open in the library or by right-clicking a bookmark in the menu or the toolbar.

14.4.3 Importing and Exporting Bookmarks

To import bookmarks from another browser or from a file in HTML format, open the library by choosing from the menu bar, Bookmarks › Show All Bookmarks. To start the Import Wizard, click Import and Backup › Import Bookmarks from HTML and choose an import location. Start the import by clicking Next. Imports from an HTML file are imported as is.

Exporting bookmarks is also done via Import and Backup in the library window. To save your bookmarks as an HTML file, choose Export Boomarks to HTML. To create a backup of your bookmarks, choose Backup. Firefox uses a JavaScript Object Notation file format (.json) for backups.

To restore a bookmark backup, click Import and Backup › Restore. Then locate the backup you want to restore from.

14.4.4 Live Bookmarks

Live Bookmarks display headlines in your bookmark menu and keep you up to date with the latest news. This enables you to save time with one glance at your favorite sites. Live bookmarks update automatically. Many sites and blogs support this format.

To create a Live Bookmark, look for orange buttons on Web sites that either read RSS or consist of a dot and three nested quarter circles. Click the icon. Usually, that will lead you to a page where all the headlines of the page are displayed. On that page, choose Subscribe Now. A dialog opens in which to select the name and location of your live bookmark. Confirm with Add. This page also lets you choose alternative applications to subscribe with, such as My Yahoo.

14.4.5 Smart Bookmark Folders

Smart bookmark folders are virtual bookmark folders that are dynamically updated. There are three smart bookmark folders: The Most Visited links are available from your bookmarks toolbar. Recently Bookmarked links and Recent Tags are located in the bookmarks menu.

14.4.6 The Bookmarks Toolbar

The Bookmarks Toolbar is displayed beneath the location bar and lets you quickly access bookmarks. You can also add, organize, and edit bookmarks directly. By default, the Bookmarks Toolbar is populated with a predefined set of bookmarks organized into several folders (see Figure 14.1, “The Browser Window of Firefox”).

To manage the Bookmarks Toolbar you can use the library as described in Section 14.4.1, “Organizing Bookmarks”. Its content is located in the folder Bookmarks Toolbar. It is also possible to manage the toolbar directly. To add a folder, bookmark, or separator, right-click an empty space in the toolbar and select the appropriate entry from the pop-up menu. To add the current page to the bar, click the icon of the Web page in the location bar and drag it to the desired position on the bookmarks toolbar. Hovering over an existing bookmark folder will automatically open it, enabling you to place the bookmark within this folder.

To manage a certain folder or bookmark, right-click it. A menu opens which lets you Delete it or change its Properties. To move or copy an entry, choose Cut or Copy and Paste it to the desired position.

14.5 Using the Download Manager

Keep track of your current and past downloads with the download manager. To start the download manager, in the menu bar, click Tools › Downloads. While downloading a file, a progress bar indicates the download status. If necessary, pause the download and resume it later. To open a downloaded file with the associated application, click Open. To open the location to which the file was saved, choose Open Containing Folder. Remove From History only deletes the entry from the download manager, however, it does not delete the file from the hard disk.

By default, all files are downloaded to ~/Downloads. To change this behavior, in the menu bar, click Edit › Preferences. Go to General. Under Downloads, either choose another location or Always ask me where to save files.

Tip
Tip: Resuming Downloads

If your browser crashes or is closed while downloading, all pending downloads will automatically be resumed in the background when starting Firefox the next time. A download that was paused before the browser was closed can manually be resumed via the download manager.

14.6 Security

Since browsing the Internet has become more risky, Firefox offers various measures to make browsing safer. It automatically checks whether you are trying to access a site known to contain harmful software (malware) or a site known to steal sensitive data (phishing) and stops you from entering these sites. The Instant Web Site ID lets you easily check a site's legitimacy, and a password manager and the pop-up blocker offer additional security. With Private Browsing, you can surf the Internet without Firefox recording data on your computer.

14.6.1 Instant Web Site ID

Firefox allows you to check the identity of a Web page with a single glance. The icon in the location bar next to the address indicates which identity information is available and whether communication is encrypted:

Gray Globe

The site does not provide any identity information and communication between Web server and browser is not encrypted. Do not exchange sensitive information with such sites.

Gray Triangle

This site is from a domain that has been verified by a certificate, so you can be sure that you are really connected to the very site it claims to be. However, the site tried to load additional elements, such as images or scripts over an insecure connection. Firefox has blocked these items. Therefore, the page can look broken.

Gray Padlock

This site is from a domain that has been verified by a certificate, so you can be sure that you are really connected to the very site it claims to be. Communication with a gray-padlock site is always encrypted.

Green Padlock

This site completely identifies itself by a certificate that ensures a site is owned by the person or organization it claims to be. This is especially important when exchanging very sensitive data (for example when doing money transactions over the Internet). In this case you can be sure to be on the Web site of your bank when it sends complete identity information. Communication with a green-padlock server is always encrypted.

To view detailed identity information, click the icon of the Web site in the location bar. In the opening pop-up, click More Information to open the Page Info window. Here, you can view the site's certificate, the encryption level, and information about stored passwords and cookies.

With the Permissions view you can set per-site permissions for image loading, pop-ups, cookies and installation permissions. The Media view lists all images, background graphics and embedded objects from a site and displays further information on each item together with a preview. It also lets you save individual items.

The Firefox Page Info Window
Figure 14.4: The Firefox Page Info Window

14.6.2 Importing Certificates

Firefox comes with a certificate store for identifying certificate authorities (CA). Using these certificates enables the browser to automatically verify certificates issued by Web sites. If a Web site issues a certificate that has not been signed by one of the CAs from the certificate store, it is not trusted. This ensures that no spoofed certificates are accepted.

Large organizations usually use their own certificate authorities in-house and distribute the respective certificates via the system-wide certificate store located at /etc/pki/nssdb. To configure Firefox (and other Mozilla tools, such as Thunderbird) to use this system-wide CA store in addition to its own, export the NSS_USE_SHARED_DB variable. For example, you can add the following line to ~/.bashrc:

export NSS_USE_SHARED_DB=1

Alternatively or additionally you can manually import certificates. To do so, in the menu bar, open the Preferences dialog by clicking Edit › Preferences. Select Advanced › Certificates › View Certificates › Your Certificates › Import and select the certificate to import. Only import certificates you absolutely trust!

14.6.3 Password Management

Each time you enter a user name and a password on a Web site, Firefox offers to store this data. A pop-up at the top of the page opens, asking you whether you want Firefox to remember the password. If you accept by clicking Remember, the password will be stored on your hard disk in an encrypted format. The next time you access this site, Firefox will automatically fill in the login data.

To review or manage your passwords, open the password manager by clicking Edit › Preferences › Security › Saved Passwords in the menu bar. The password manager opens with a list of sites and their corresponding user names. By default, the passwords are not displayed. You can click Show Passwords to display them. To delete single or all entries from the list, click Remove or Remove All, respectively.

To protect your passwords from unauthorized access, you can set a master password that is required when managing or adding passwords. In the menu bar, click Edit › Preferences, choose the category Security and activate Use a Master Password.

14.6.4 Private Browsing

By default, Firefox keeps track of your browsing history by storing content and links of visited Web sites, cookies, downloads, passwords, search terms and formula data. Collecting and storing this data makes browsing faster and more convenient. However, when you use a public terminal or a friend's computer, for example, you could turn this behavior off. In Private Browsing mode Firefox will not keep track of your browsing history nor will it cache the content of pages you have visited.

To enable the Private Browsing mode, in the menu bar, click File › New Private Window. The current Web site and all open tabs will be replaced by the Private Browsing information screen. As long as you will browse in private mode, the string (Private Browsing) will be displayed in the titlebar of the window.

Disable Private Browsing by closing the private window.

To make Private Browsing the default mode, open the Privacy tab in the Preference window as described in Section 14.7.1, “Preferences”, set the option Firefox will: to Use custom settings for history and then choose Always use private browsing mode.

Warning
Warning: Bookmarks and Downloads

Downloads and bookmarks you made during Private Browsing mode will be kept.

14.7 Customizing Firefox

Firefox can be customized extensively.

  • Change the way Firefox behaves by altering its preferences.

  • Add functionality by installing extensions.

  • Change the look and feel by installing themes.

To manage extensions, themes and plug-ins, Firefox has an add-on manager.

14.7.1 Preferences

Firefox offers a wide range of configuration options. These are available by choosing Edit › Preferences in the menu bar. Each option is described in detail in the online help, which can be accessed by clicking the question mark icon in the dialog.

The Preferences Window
Figure 14.5: The Preferences Window

14.7.1.1 Session management

By default, Firefox automatically restores your session—windows and tabs—only after it has crashed, or after a restart because of an extension. However, it can be configured to restore a session every time it is started: Open the Preferences dialog as described in Section 14.7.1, “Preferences” and go to the category General. Set the option When Firefox Starts: to Show My Windows and Tabs from Last Time.

When you have multiple windows open they will only be restored the next time when you close all of them at once with File › Quit (from the menu bar) or with CtrlQ. If you close the windows one by one, only the last window will be restored.

14.7.1.2 Language Preferences for Web Sites

When sending a request to a Web server, the browser always sends the information about which language is preferred by the user. Web sites that are available in more than one language (and are configured to evaluate this language parameter) will display their pages in the language the browser requests. On SUSE Linux Enterprise Server, the preferred language is preconfigured to use the same language as the desktop. To change this setting, open the Preferences window as described in Section 14.7.1, “Preferences”, go to the category Content and Choose your preferred language.

14.7.1.3 Spell Checking

By default, Firefox spell-checks what you type when typing into multiple-line text boxes. Misspelled words are underlined in red. To correct a word, right-click it and select the correct spelling from the context menu. You may also add the word to the dictionary, if it is correct.

To change or add a dictionary, right-click anywhere in a multi-line text box and select the appropriate option from the context menu. Here you may also disable spell-checking for this text box. If you want to globally disable spell checking, open the Preferences window as described in Section 14.7.1, “Preferences” and go to the category Advanced. Deactivate Check My Spelling As I Type.

14.7.2 Add-ons

Extensions let you personalize Firefox to fit your needs. With extensions, you can change the look and feel of Firefox, enhance existing functionality, and add functions. For example, extensions can enhance the download manager, show the weather, or control Web music players. Other extensions assist Web developers or increase security by blocking content such as ads or scripts.

There are thousands of extensions available for Firefox. With the add-ons manager, you can install, enable, disable, update, and remove extensions.

If you do not like the standard look and feel of Firefox, install a new theme. Themes do not change the functionality, only the appearance of the browser.

14.7.2.1 Installing Add-ons

To add an extension or theme, start the add-ons manager with Tools › Add-Ons from the menu bar. It opens on the Get Add-Ons tab either displaying a choice of recommended add-ons or the results of your last search.

Use the Search All Add-Ons field to search for specific add-ons. Click an entry in the list to view a short description. Install the add-on by clicking Install or open a Web page with detailed information by clicking the More link.

Installing Firefox Extensions
Figure 14.6: Installing Firefox Extensions

To activate freshly installed extensions or themes, Firefox sometimes needs to be restarted by clicking Restart now in the add-ons manager. Restart this way to make sure that your browsing session will be restored.

14.7.2.2 Managing Add-ons

The Add-ons Manager also offers a convenient interface to manage extensions, themes, and plug-ins. Extensions can be enabled, disabled or uninstalled. If an extension is configurable, its configuration options can be accessed via the Preferences button. In the Appearance tab you may Uninstall a theme, or activate a different theme by clicking Enable. Pending extension and theme installations are also listed. Select Cancel to stop the installation. Although you cannot install Plug-Ins as a user, you may disable or enable them with the Add-ons manager.

Some add-ons require you to restart the browser when you uninstall or disable them. In such cases, after clicking either of these actions, a Restart now link appears in the add-ons manager.

14.8 Printing from Firefox

Before you actually print a Web page, you can use the print preview function to control how the printed page will look like. From the menu bar, choose File › Print Preview. Configure paper size and orientation per printer with Page Setup.

To print a Web page either choose, from the menu bar, File › Print or press CtrlP. The Printer dialog opens. To print with the default options click Print.

The Printer dialog also offers extensive configuration options to fine-tune the printout. On the General tab, choose a printer, the range to print, the number of copies and the order. Page Setup lets you specify the number of pages per side, the scaling factor, and paper source and type. If the printer supports it, you can also activate double-sided printing here. Control how frames, backgrounds, header and footer are printed on the Options tab.

14.9 For More Information

To get more information about Firefox see the following links:

Mozilla forums: https://www.mozilla.org/about/forums/
Main Menu reference: http://support.mozilla.org/kb/Menu+reference
Preferences reference: http://support.mozilla.org/kb/Options+window
Keyboard shortcuts: http://support.mozilla.org/kb/Keyboard+shortcuts

15 Evolution: E-Mailing and Calendaring

  • Filename: apps_evolution.xml
  • ID: cha.gnome.evolution

Evolution makes storing, organizing, and retrieving your personal information easy, so you can work and communicate more effectively with others. It is a professional groupware program and an important part of the Internet-connected desktop.

Evolution can help you work in a group by handling e-mail, contact information, and one or more calendars. It can do that on one or several computers, connected directly or over a network, for one person or for large groups.

Evolution helps you accomplish common daily tasks quickly. For example, you can easily reuse appointment or contact information sent to you by e-mail, or send e-mails to a contact or appointment. If you receive lots of e-mail, you can use advanced features like search folders, which let you save searches as though they were ordinary e-mail folders.

This chapter introduces you to Evolution and helps you get started. For more details, refer to the Evolution application help.

15.1 Starting Evolution

To start Evolution, click Applications › Internet › Evolution.

15.2 Setup Assistant

The first time you start Evolution, it opens an assistant to help you set up e-mail accounts and import data from other applications.

The Evolution Account Assistant helps you provide all the required information.

15.2.1 Restoring from a Backup File

When the assistant starts, the Welcome page is displayed. Proceed to the Restore from Backup page. If you previously backed up your Evolution configuration and want to restore it, activate the restoration option and select the backup file in the file chooser dialog.

Otherwise, proceed to Identity.

15.2.2 Defining Your Identity

The Identity page is the next step in the assistant.

  1. Type your full name in the Full Name field.

  2. Type your e-mail address in the E-mail Address field.

  3. (Optional) (Optional) Type an address in the Reply-To field.

    Only use this field if you want replies to e-mails from you to be sent to a different e-mail address.

  4. (Optional) (Optional) Type your organization name in the Organization field.

    This is the company where you work, or the organization you represent when you send e-mails.

  5. Proceed to the next page.

15.2.3 Receiving Mail

The Receiving E-mail page lets you determine the server that you want to use to receive e-mail.

You need to specify the type of server you want to receive mail from. If you are not sure about the type of server, contact your system administrator or e-mail provider.

Select a server type in the Server Type list. The following is a list of available server types:

Exchange Web Services:  Allows you to connect to newer Microsoft Exchange servers to synchronize e-mail, calendar, and contact information. This is only available if you have installed the connector for Microsoft* Exchange* which is packaged in evolution-ews .

IMAP+:  Keeps the e-mail on your server, so you can access your e-mail from multiple systems.

POP:  Downloads your e-mail to your hard disk for permanent storage, freeing up space on the e-mail server.

USENET News:  Connects to a news server and downloads a list of available news digests.

Local Delivery:  If you want to move e-mail from the spool and store it in your home directory, you need to provide the path to the mail spool you want to use. If you want to leave mail in your system’s spool files, select Standard Unix Mbox Spool File instead.

MH Format Mail Directories:  To download your e-mail using mh or an mh-style program, you need to provide the path to the mail directory you want to use.

Maildir Format Mail Directories:  If you download your e-mail using Qmail or another Maildir-style program, select this option. You need to provide the path to the mail directory you want to use.

Standard Unix Mbox Spool File or Directory:  To read and store e-mail in the mail spool on your local system, select this option. You need to provide the path to the mail spool you want to use.

None:  If you do not plan to check e-mail with this account, select this option. There are no configuration options.

15.2.3.1 Configuration Options for IMAP+, POP, and USENET

If you selected IMAP+, POP, or USENET News as the server type, you need to specify additional information.

If you are not sure about the correct server address, user name or security setting, contact your system administrator or e-mail provider.

  1. Type the host name of your e-mail server into the text box Server.

  2. Type your user name for the account into the text box Username.

  3. Choose a security setting supported by your mail server. For security reasons, avoid using No Encryption.

  4. Select your authentication type in the Authentication list. To have Evolution check for supported authentication types, click Check for Supported Types. Then choose one of the options without a strikeout.

    Some servers do not announce the authentication mechanisms they support. Therefore clicking this button is not a guarantee that the shown mechanisms actually work.

  5. Proceed to the next page.

15.2.3.2 Configuration Options for Exchange Web Services

If you selected Exchange Web Services as the server type, you need to specify additional information.

If you are not sure about the correct server address, user name or security setting, contact your system administrator or e-mail provider.

  1. Type your user name for the account into the text box Username.

  2. Type the EWS URL of your e-mail server into the text box Host URL.

    If available, type the address of an Offline Address Book into the text box OAB URL.

    If your login name and the name of your mailbox differ, select Open Mailbox of other user. Then type the mailbox name into the text box below.

  3. Select an authentication type in the Authentication list. To have Evolution check for supported authentication types, click Check for Supported Types. Then choose one of the options without a strikeout.

    Some servers do not announce the authentication mechanisms they support. Therefore clicking this button is not a guarantee that the shown mechanisms actually work.

  4. Proceed to the next page.

15.2.3.3 Local Configuration Options

If you selected Local Delivery, MH-Format Mail Directories, Maildir-Format Mail Directories, or Standard Unix Mbox Spool File or Directory, specify the path to the local files or directories in the path field.

15.2.4 Receiving Options

After you have selected a mail delivery mechanism, you can set some preferences for its behavior.

15.2.4.1 IMAP+ Receiving Options

If you selected IMAP+ as the receiving server type, you will now see a page of options to specify the behavior of Evolution.

  1. You can choose from the following options:

    Check for new messages every ... minutes

    Select if you want Evolution to automatically check for new mail. Set how often to check.

    Check for new message in all folders

    Select if you want to check for new messages in all folders.

    Check for new message in subscribed folders

    Select if you want to check for new messages in subscribed folders.

    Use Quick Resync if the server supports it

    Select to use Quick Resync which makes browsing mail faster on supported servers.

    Listen for server change notifications

    Select if you want Evolution to listen for change notifications. If you activate this option, Evolution will show you mail as it arrives. Therefore, you can usually deactivate Check for new messages every ... minutes.

    Show only subscribed folders

    Select if you want Evolution to show only subscribed folders.

    You can unsubscribe from folders to cut down on the number of irrelevant folders shown in Evolution and to reduce the amount of mail that is downloaded.

    Apply filters to new messages in all folders

    Select if you want to apply filters to new messages, and whether to do so in all folders or only in the Inbox folder.

    Check new messages for Junk contents

    Select if you want to check new messages for junk content, and whether to do so in all folders or only in the Inbox folder.

    Automatically synchronize remote mail locally

    Select this to download all your mail, so you can read it offline.

  2. Proceed to the next page.

15.2.4.2 POP Receiving Options

If you selected POP as the receiving server type, you will now see a page of options to specify the behavior of Evolution.

  1. You can choose from the following options:

    Check for new messages every ... minutes

    Select if you want Evolution to automatically check for new mail. Set how often to check.

    Leave messages on server

    Select if you want leave your mail on the server or delete it on the server when you download it to your computer. You can also set a period of time for which the messages will be kept on the server after they were downloaded.

    Disable support for all POP3 extensions

    Disabling POP3 extensions can help with old or misconfigured servers. Select if you have trouble receiving mail.

  2. Proceed to the next page.

15.2.4.3 USENET News Receiving Options

If you selected USENET News as the receiving server type, you will now see a page of options to specify the behavior of Evolution.

  1. You can choose from the following options:

    Check for new messages every ... minutes

    Select if you want Evolution to automatically check for new mail. Set how often to check.

    Apply filters to new messages in all folders

    Select if you want to apply filters to new messages.

    Show folders in short notations

    Abbreviate folder names, for example, comp.os.linux appears as c.o.linux.

    In the subscription dialog, show relative folder names

    Display only the name of the folder. For example, the folder evolution.mail would appear as evolution.

  2. Proceed to the next page.

15.2.4.4 Exchange Web Services Receiving Options

If you selected Exchange Web Services as the receiving server type, you will now see a page of options to specify the behavior of Evolution.

  1. You can choose from the following options:

    Check for new messages every ... minutes

    Select if you want Evolution to automatically check for new mail. Set how often to check.

    Check for new message in all folders

    Select if you want to check for new messages in all folders.

    Listen for server change notifications

    Select if you want Evolution to listen for change notifications. If you activate this option, Evolution will show you mail as it arrives. Therefore, you can usually deactivate Check for new messages every ... minutes.

    Apply filters to new messages in all folders

    Select if you want to apply filters to new messages.

    Check new messages for Junk contents

    Select if you want to check new messages for junk content, and whether to do so in all folders or only in the Inbox folder.

    Automatically synchronize remote mail locally

    Select this to download all your mail, so you can read it offline.

    Connection timeout (in seconds)

    Set maximum time to wait for an answer from the server.

    Cache offline address book

    If you provided an OAB URL in the prior step, you can select caching an address book. This will make the address book available when offline.

  2. Proceed to the next page.

15.2.4.5 Local Delivery Receiving Options

If you selected that you want to receive mail through Local Delivery, you will now see a page of options to specify the behavior of Evolution.

  1. Select Check for new messages every ... minutes if you want Evolution to automatically check for new mail. Set how often to check.

  2. Proceed to the next page.

15.2.4.6 MH-Format Mail Directories Receiving Options

If you selected that you want to receive mail through MH-Format Mail Directories, you will now see a page of options to specify the behavior of Evolution.

  1. Select Check for new messages every ... minutes if you want Evolution to automatically check for new mail. Set how often to check.

    Select Use the .folders summary file to use the .folders summary file.

  2. Proceed to the next page.

15.2.4.7 Maildir-Format Mail Directories Receiving Options

If you selected that you want to receive mail through Maildir-Format Mail Directories, you will now see a page of options to specify the behavior of Evolution.

  1. Select Check for new messages every ... minutes if you want Evolution to automatically check for new mail. Set how often to check.

    Select Apply filters to new messages in Inbox if you want to apply filters to new messages.

  2. Proceed to the next page.

15.2.4.8 Standard Unix Mbox Spool or Directory Receiving Options

If you selected that you want to receive mail through a Unix mbox Spool File or Directories, you will now see a page of options to specify the behavior of Evolution.

  1. Select Check for new messages every ... minutes if you want Evolution to automatically check for new mail. Set how often to check.

    Select Apply filters to new messages in Inbox if you want to apply filters to new messages.

  2. Select Store status headers in Elm/Pine/Mutt format to store status headers in a way compatible with Elm, Pine, and Mutt.

  3. Proceed to the next page.

15.2.5 Sending Mail

Now that you have entered information about how you plan to receive mail, Evolution needs to know about how you want to send it. Usually, a separate server configuration is necessary for this. Otherwise, this page will be skipped.

Select a server type from the Server Type list.

The following server types are available:

Sendmail:  Uses the Sendmail program to send mail from your system. Sendmail is more flexible, but is not as easy to configure, so you should select this option only if you know how to set up a Sendmail service.

SMTP:  Sends mail using a separate mail server. This is the most common choice for sending mail. If you choose SMTP, there are additional configuration options.

Procedure 15.1: SMTP Configuration
  1. Type the host address in the Server field.

    If you are not sure what your host address is, contact your system administrator or e-mail provider.

  2. Select if your server requires authentication.

    If you selected that your server requires authentication, you need to provide the following information:

    1. Choose a security setting supported by your mail server. For security reasons, avoid using No Encryption.

    2. Select your authentication type in the Authentication list.

      or

      Click Check for Supported Types to have Evolution check for supported types. Then choose one of the options without a strikeout.

      Some servers do not announce the authentication mechanisms they support. Therefore, clicking this button is not a guarantee that the shown mechanisms actually work.

    3. Type your user name in the Username field.

  3. Proceed to the next page.

15.2.6 Final Steps

Now that you have finished the e-mail configuration process, you need to give the account a name. The name can be any name you prefer. Type your account name on the Name field. Proceed to the next page and confirm your changes.

Depending on your configuration, you may now be asked for your e-mail passwords and whether you want to save them or want to always enter them when starting Evolution.

The Evolution main window will then open for the first time.

15.3 Using Evolution

Now that the first-run configuration has finished, you are ready to begin using Evolution. This section sums up the most important parts of the user interface.

Evolution Window
Figure 15.1: Evolution Window
Menu Bar

The menu bar gives you access to nearly all of the features of Evolution.

Folder List

The folder list gives you a list of the available folders for each account. To see the contents of a folder, click the folder name. The contents are displayed in the e-mail list.

Toolbar

The toolbar gives you fast and easy access to the frequently used features in each component.

Search Bar

The search bar lets you search for e-mails. You can filter e-mails, contacts, and calendar entries and tasks using different criteria: a label, a search term, and an account or folder. The Search bar can also save frequently used searches to a search folder.

Message List

The message list displays a list of e-mails that you have received. To view an e-mail in the preview pane, select the e-mail.

Shortcut Bar

The shortcut bar at the left lets you switch between folders and program components.

Statusbar

The statusbar periodically displays a message, or informs you about the progress of a task, such as sending e-mail.

On the far left, you will find the Online/Offline indicator. Click the Online/Offline indicator to switch between being using Evolution in online or offline mode.

Preview Pane

The preview pane displays the contents of the e-mails that are selected in the e-mail list.

15.3.1 The Menu Bar

The menu bar’s contents always provide all the possible actions for any view of your data.

File:  Anything related to a file or to the operations of the application usually falls under this menu, such as creating things, saving them to disk, printing them, and quitting the program itself.

Edit:  Contains tools to edit text and most configuration options.

View:  Allows configuring the appearance of Evolution.

Message:  Contains actions that can be applied to a message.

Folder:  Contains actions that can be performed on folders.

Search:  Lets you search for messages, or phrases within a message. You can also see previous searches you have made.

Help:  Opens the Evolution application help.

15.3.2 The Shortcut Bar

The shortcut bar is the column on the left side of the main window. At the top, there is a list of folders for the selected Evolution component. The buttons at the bottom are shortcuts to the individual components, such as Mail and Contacts.

The folder list organizes your e-mail, calendars, contact lists, and task lists in a tree. Most people find one to four folders at the base of the tree, depending on the component and their system configuration. Each Evolution component has at least one, called On This Computer, for local information. For example, the folder list for the e-mail component shows all your e-mail accounts, local folders, and search folders.

If you receive large amounts of e-mail, you need additional ways to organize it. In Evolution, you can create own e-mail folders, address books, calendars, task lists, or memo lists.

15.3.2.1 Creating a folder

To create a new folder:

  1. Click File › New › Mail Folder.

  2. Type the name of the folder in the Folder Name field.

  3. Select the location of the new folder.

  4. Click Create.

15.3.2.2 Folder Management

Right-click a folder or subfolder to display a menu with the following options:

Mark All Messages As Read Marks all the messages in the folder as read.

New Folder Creates a new folder or subfolder in the same location.

Copy Folder To Copies the folder to a different location. When you select this item, Evolution offers a choice of locations to copy the folder to.

Move Folder To Moves the folder to another location.

Delete Deletes the folder and all contents.

Rename Lets you change the name of the folder.

Refresh:  Refreshes the folder.

Properties:  Shows the number of total and unread messages in a folder.

You can also rearrange folders and messages by dragging and dropping them.

Any time new e-mail arrives in an e-mail folder, that folder label is displayed in bold text, along with the number of new messages in that folder.

15.3.3 Using E-Mail

The e-mail component of Evolution has the following standout features:

  • It supports multiple e-mail sources from many protocols.

  • It lets you guard your privacy with encryption.

  • It can speedily handle large amounts of e-mail.

  • Search folders allow you to come back to often-used searches.

Below is a summary of the user interface elements of the e-mail window.

Message List

The message list displays all the e-mails that you have. This includes all your read and unread messages and e-mail that is flagged to be deleted. With the Show drop-down box above the message you can filter the message list view using predefined and custom labels.

Preview Pane

This is where your e-mail is displayed.

If you find the preview pane too small, you can resize the pane, enlarge the whole window, or double-click the message in the message list to have it open in a new window. To change the size of a pane, drag the divider between the two panes.

As with folders, you can right-click messages in the message list and get a menu of possible actions. This includes moving or deleting them, creating filters or search folders based on them, and marking them as junk mail.

Actions related to e-mail, like Reply and Forward, appear as buttons in the toolbar and are also located in the right-click menu.

Templates

Evolution allows you to create and edit message templates that you can use at any time to send mail with the same pattern.

15.3.4 Calendaring

To begin using the calendar, click Calendars in the shortcut bar. By default, the calendar shows today’s schedule on a ruled background. At the upper right, there is a Tasks list, where you can keep a list of tasks separate from your calendar appointments. Below that, there is a list for memos.

Appointment List

The appointment list displays all your scheduled appointments.

Month Pane

The month pane is a small view of a calendar month. You can also select a range of days in the month pane to display a custom range of days in the appointment list.

Tasks

Tasks are distinct from appointments because they generally do not have times associated with them. You can see a larger view of your task list by clicking Tasks in the shortcut bar.

Memos

Memos, like Tasks, do not have times associated with them. You can see a larger view of your Memo list by clicking Memos in the shortcut bar.

15.3.5 Managing Contacts

To use the contacts component, click Contacts in the shortcut bar. The Evolution contacts component can handle all of the functions of an address book or phone book.

It does, however, also do more than a paper book. To share your address book on a network, you can use LDAP directories. To create a new contact entry, right-click an e-mail address or double-click an empty space in the right pane. You can also search contacts using the search bar.

By default, the display shows all your contacts in alphabetical order, in a card-based view. You can select other views from the View menu.

15.4 For More Information

Get more information about Evolution from the application help available via F1.

Find more information on the project home page https://wiki.gnome.org/Apps/Evolution.

16 Empathy: Instant Messaging

  • Filename: apps_empathy.xml
  • ID: cha.gnome.empathy

Empathy is an instant messaging (IM) client that allows you to connect to multiple accounts simultaneously. Chat live with your contacts in one tabbed interface, regardless of which IM system they use. Empathy uses Telepathy for protocol support.

Empathy supports the following instant messaging protocols: Google Talk (Jabber/XMPP), MSN, IRC, Salut, AIM, Facebook, Yahoo!, Gadu Gadu, Groupwise®, ICQ and QQ. (The supported protocols depend on installed Telepathy Connection Manager components.)

In the following, learn how to set up Empathy and how to communicate with your contacts.

16.1 Starting Empathy

To start Empathy, select Applications › Internet › Empathy.

16.2 Configuring Accounts

To use Empathy, you must already have an account for the messaging service you want to use. For example, to use Empathy to chat via AIM, you must first have an AIM account.

Procedure 16.1: Adding and Editing Accounts in Empathy
  1. To start Empathy, select Applications › Internet › Empathy.

    If you start Empathy for the first time, a message appears, prompting you to configure an account.

  2. Enter your account data. The Messaging and VoIP Accounts dialog shows the accounts that have been configured so far.

  3. To add another account:

    1. In the Messaging and VoIP Accounts dialog, click the plus icon.

    2. Choose the type of account you want to configure, enter your user ID and password for the account and click Add. The dialog to add or modify accounts differs for each type of account, depending on what setup options are available for that account.

  4. To enter or modify connection data for an account:

    1. Select the account and click Edit Connection Parameters › Advanced.

    2. Enter a server name and a port to use for the connection. Specify additional parameters, such as encryption options, if necessary. If you are unsure which parameters to use, refer to your system administrator or messaging service.

    3. Click Apply to confirm your changes.

To go online with your account, turn the account switch on. When prompted for your password, enter it.

To disable the account, turn the switch off. If you are finished with the configuration of your accounts, close the Messaging and VoIP Accounts dialog.

16.3 Managing Contacts

Use the Contact List to manage your contacts. You can add and remove contacts and organize them in groups, so they are easy to find.

Procedure 16.2: Adding Contacts
  1. To add a contact, click Contacts › Add Contacts.

  2. Select the Account for which you want to add a contact.

  3. As Identifier, enter the name or user ID of the person you want to add.

  4. By default, Alias will show the same entry, but you can enter a different name or nickname for the contact person here.

    As soon as you start typing into the Identifier text box, the dialog will also show any groups that you have already defined.

  5. To add the new contact to a group, activate the respective group's check box.

  6. To create a new group, type a group name into the text box next to Add Group and click Add Group.

  7. Click Add to confirm your changes and to close the dialog.

In case the groups or the newly added contacts are not displayed in the Contact List, check the Empathy preferences by clicking Preferences › General. Activate Show offline contacts and Show groups to make all contacts and groups appear in the Contact List.

To remove a contact from the list, right-click the name of that contact, select Remove and confirm your choice.

16.4 Chatting with Friends

To chat with other participants, you need to be connected to the Internet. After a successful login, you are usually marked as Available in the Contact List, and thus visible to others. To change your status, click the drop-down box at the top of the Contact List and select another option.

To open a chat session, double-click a contact name in the Contact List. The chat screen opens. Type your message, then press Enter to send.

If you open more than one chat session, the new session appears as a tab in the existing chat window. To see all messages of a session and to be able to write a reply, click the tab of that session. To see multiple session side by side, use the mouse to drag a tab out of the window. A second window will open.

To close a chat session, close the tab or window for it.

16.5 For More Information

This chapter explained the Empathy options you need to know about to set up Empathy and communicate with your contacts. It does not explain all features and options available. For more information, open Empathy, then click Help.

For updates about new features and for the latest information, refer to the home page of the project at https://wiki.gnome.org/Apps/Empathy.

17 Ekiga: Using Voice over IP

  • Filename: apps_ekiga.xml
  • ID: cha.ekiga
Abstract

Ekiga is an application you can use for making phone calls via Voice over IP (VoIP), for video conferencing and for instant messaging.

Note
Note: Ekiga May Not Be Installed

Before proceeding, make sure that the package ekiga is installed.

Before starting, make sure that the following requirements are met:

  • Your sound card is properly configured.

  • A headset or a microphone and speakers are connected to your computer.

  • For dialing in to regular phone networks, a SIP account is required. SIP (Signaling protocol for Internet Telephony) is the protocol used to establish sessions for audio and video conferencing or call forwarding.

    There are many VoIP providers all over the world. One provider is the Ekiga project itself, go to https://ekiga.im to learn more.

  • For video conferencing: A Web cam is connected to your computer.

17.1 Starting Ekiga

Start Ekiga by clicking Applications › Internet › Ekiga Softphone.

17.2 Configuring Ekiga

On first start, Ekiga opens a configuration assistant that requests all data needed to configure Ekiga. Proceed as follows:

  1. Click Forward.

  2. Enter your full name (name and surname). Click Forward.

  3. Enter your ekiga.net account data or choose not to register with http://www.ekiga.net. Click Forward.

  4. Enter your Ekiga Call Out Account data or choose not to register with http://www.ekiga.net. Click Forward.

  5. Set your connection type and speed. Click Forward.

  6. Configure the audio devices to use by choosing the audio ringing, output and input device driver. In general, you can keep the Default setting. Click Forward.

  7. Choose a video input device, if available. Click Forward.

  8. Check the summary of your settings and apply them.

  9. If registration fails after making changes to your configuration, restart Ekiga.

Ekiga allows you to maintain multiple accounts. To configure an additional account, proceed as follows:

  1. Open Edit › Accounts.

  2. Choose Accounts › Add <account type>. If you are unsure, select Add a SIP Account.

  3. Enter the Registrar to which you have registered. This is usually an IP address or a host name that will be given to you by your Internet Telephony Service Provider. Enter User, and Password according to the data provided by your provider.

  4. Make sure Enable account is activated and leave the configuration dialog with OK. The account is displayed in the Ekiga main window, including its Status, which should change to Registered.

17.3 The Ekiga User Interface

The user interface has different modes. To switch between views, use the toolbar. The first mode is Contacts, the second is Dialpad and the last one is Call History. Click the camera icon to open the Call Window. It displays images from your local Web cam (or from a remote Web cam during a call).

Ekiga User Interface
Figure 17.1: Ekiga User Interface

By default, Ekiga opens in the Contacts mode. This view shows you a local address book which lets you quickly open connections to often-used numbers.

Many of the functions of Ekiga are available with key combinations. Table 17.1, “Key Combinations for Ekiga” summarizes the most important ones.

Table 17.1: Key Combinations for Ekiga

Key Combination

Description

CtrlO

Initiate a call with the current number.

Esc

Hang up.

CtrlN

Add a contact to your address book.

CtrlB

Open the Address Book dialog.

H

Hold the current call.

T

Transfer the current call to another party.

M

Suspend the audio stream of the current call.

P

Suspend the video stream of the current call.

CtrlW

Close the Ekiga user interface.

CtrlQ

Quit Ekiga.

CtrlE

Start the account manager.

CtrlJ

Activate Call Panel on the main user interface.

Ctrl+

Zoom in to the picture from the Web cam.

Ctrl-

Zoom out on the picture from the Web cam.

Ctrl0

Return to the normal size of the Web cam display.

F11

Use full screen for the Web cam.

17.4 Making a Call

After Ekiga is properly configured, making a call is easy.

  1. Switch to the Dialpad mode.

  2. Enter the SIP address of the party to call at the bottom of the window. The address should look like:

    • for direct local calls: sip:username@domainname or username@hostname

    • sip:username@domainname or userid@sipserver

  3. Click Call or press CtrlO and wait for the other party to pick up the phone.

  4. To end the call, click Hang up or press Esc.

If you need to tweak the sound parameters, click Edit › Preferences.

17.5 Answering a Call

Ekiga can receive calls in two different ways. First, it can be called directly with sip:user@host, or via SIP provider. Most SIP providers enable you to receive calls from a normal land-line to your VoIP account. Depending on the mode in which you use Ekiga, there are several ways in which you are alerted to an incoming call:

Normal Application

Incoming calls can only be received and answered if Ekiga is already started. You can hear the ring sound on your headset or your speakers. If Ekiga is not started, the call cannot be received.

Panel Applet

Normally, the Ekiga panel applet runs silently without giving any notice of its existence. This changes when a call comes in. The main window of Ekiga opens and you hear a ringing sound on your headset or speakers.

Once you have noticed an incoming call, click Accept to answer the call then start talking. If you do not want to accept this call, click Reject. It is also possible to transfer the call to another SIP address.

17.6 Using the Address Book

Ekiga can manage your SIP contacts. All of the contacts are displayed in the Contacts tab, shown in the main window after start-up. To add a contact or a new contact group, select Chat › Add Contact.

If you want to add a new group, enter the group name into the bottom text box and click Add. The new group is then added to the group list and preselected.

The following entries are required for a valid contact:

Name

Enter the name of your contact. This may be a full name, but you can also use a nickname here.

Address

Enter a valid SIP address for your contact.

Groups

If you have many contacts, add your own groups.

To call a contact from the address book, double-click the contact. The call is initiated immediately.

17.7 For More Information

The official home page of Ekiga is http://www.ekiga.org/. This site offers answers to frequently asked questions and more detailed documentation.

For information about the support of the H323 teleconferencing protocol in Linux, see http://www.voip-info.org/wiki/view/H.323. This is also a good starting point when searching for projects supporting VoIP.

To set up a private telephone network, you might be interested in the PBX software Asterisk http://www.asterisk.org/. Find information about it at http://www.voip-info.org/wiki-Asterisk.

Part V Graphics and Multimedia

18 GIMP: Manipulating Graphics

GIMP (the GNU Image Manipulation Program) is a program for creating and editing raster graphics. In most aspects, its features are comparable to those of Adobe* Photoshop* and other commercial programs. Use it to resize and retouch photographs, design graphics for Web pages, create covers for your custom CDs, or almost any other graphics project. It meets the needs of both amateurs and professionals.

19 GNOME Videos

GNOME Videos is the default movie player. GNOME Videos provides the following multimedia features:

20 Brasero: Burning CDs and DVDs

Brasero is a GNOME program for writing data and audio CDs and DVDs. Start the program from the main menu by clicking Applications › Sound & Video › Brasero.

The following sections are a quick introduction on how to create your own CD or DVD.

18 GIMP: Manipulating Graphics

  • Filename: apps_gimp.xml
  • ID: cha.gimp
Abstract

GIMP (the GNU Image Manipulation Program) is a program for creating and editing raster graphics. In most aspects, its features are comparable to those of Adobe* Photoshop* and other commercial programs. Use it to resize and retouch photographs, design graphics for Web pages, create covers for your custom CDs, or almost any other graphics project. It meets the needs of both amateurs and professionals.

GIMP is an extremely complex program. Only a small range of features, tools, and menu items are discussed in this chapter. See Section 18.8, “For More Information” for ideas of where to find more information about the program.

18.1 Graphics Formats

There are two main types of digital graphics: raster and vector. GIMP is intended for working with raster graphics, which are most often used for digital photographs or scanned images.

Raster Images.  A raster image is a collection of pixels: Small blocks of color that create an entire image when put together. High resolution images contain a large number of pixels. Because of this, such image files can easily become quite large. It is not possible to increase the size of a raster image without losing quality.

GIMP supports most common formats of raster graphics, like JPEG, PNG, GIF, BMP, TIFF, PSD, and more.

Vector Images.  Unlike raster images, vector images do not store information about individual pixels. Instead, they use geometric primitives such as points, lines, curves, and polygons. Vector images can be scaled very easily. Depending on their content, vector image files can both be very small or very large. However, their file size is usually independent of their display size.

The disadvantage of vector images is that they are not good at representing complex images with many colors such as photographs. There are many specialized applications for vector graphics, for example Inkscape. GIMP has very limited support for vector graphics. For example, GIMP can open and rasterize vector graphics in SVG format or work with vector paths.

GIMP supports only the most common color spaces:

  • RGB images with 8 bits per channel. This equals 24 bits per pixel in RGB images without an alpha channel (transparency). With an alpha channel, that equals 32 bits per pixel.

  • Grayscale images with 8 bits per pixel.

  • Indexed images with up to 255 colors.

Many high-end digital cameras produce image files with color depths above 8 bits per channel. If you import such an image into GIMP, you will lose some color information. GIMP also does not support a CMYK color mode for professional printing.

18.2 Starting GIMP

To start GIMP, select Applications › Graphics › GIMP.

18.3 User Interface Overview

By default, GIMP shows three windows. The toolbox, an empty image window with the menu bar, and a window containing several docked dialogs. The windows can be arranged on the screen as you need them. If they are no longer needed, they can also be closed. Closing the image window when it is empty quits the application.

In the default configuration, GIMP saves your window layout when you quit. Dialogs left open reappear when you next start the program.

If you want to combine all windows of GIMP, activate Windows › Single-Window Mode.

18.3.1 The Image Window

If there is currently no image open, the image window is empty, containing only the menu bar and the drop area, which can be used to open any file by dragging and dropping it there. Every new, opened, or scanned image appears in its own window. If there is more than one open image, each image has its own image window. There is always at least one image window open.

In Single-Window Mode, all image windows are accessible from a tab bar at the top of the window.

The menu bar at the top of the window provides access to all image functions. You can also access the menu by right-clicking the image or clicking the small arrow button in the top left corner of the rulers.

The File menu offers the standard file operations, such as New, Open, Save, Print and Close. Quit quits the application.

With the items in the View menu, control the display of the image and the image window. New View opens a second display window of the current image. Changes made in one view are reflected in all other views of that image. Alternate views are useful for magnifying a part of an image for manipulation while seeing the complete image in another view. Adjust the magnification level of the current window with Zoom. When Fit Image in Window is selected, the image window is resized to fit the current image display exactly.

18.3.2 The Toolbox

The toolbox contains drawing tools, a color selector, and a freely configurable space for options pages. If you accidentally close the toolbox, you can reopen it by clicking Tools › New Toolbox.

To find out what a particular tool does, hover over its icon. At the very top, there is a drop area which can be used to open any image file by simply dragging and dropping it there.

The Toolbox
Figure 18.1: The Toolbox

The current foreground and background color are shown in two overlapping boxes. The default colors are black for the foreground and white for the background. Swap the foreground and background color with the bent arrow icon to the upper right of the boxes. Use the black and white icon to the lower left to reset the colors to the default. Click the box to open a color selection dialog.

Under the toolbox, a dialog shows options for the currently selected tool. If it is not visible, open it by double-clicking the icon of the tool in the toolbox.

18.3.3 Layers, Channels, Paths, Undo

Layers shows the different layers in the current image and can be used to manipulate the layers. Information is available in Section 18.6.6, “Layers”.

Channels shows the color channels of the current image and can manipulate them.

Paths are a vector-based method of selecting parts of an image. They can also be used for drawing. Paths shows the paths available for an image and provides access to path functions. Undo shows a limited history of modifications made to the current image. Its use is described in Section 18.6.5, “Undoing Mistakes”.

18.4 Getting Started

Although GIMP can be a bit overwhelming for new users, most quickly find it easy to use after they work out a few basics. Crucial basic functions are creating, opening, and saving images.

18.4.1 Creating a New Image

  1. To create a new image, select File › New. This opens a dialog in which you can make settings for the new image.

  2. If desired, select a predefined setting called a Template.

    Note
    Note: Custom Templates

    To create a custom template, select Windows › Dockable Dialogs › Templates and use the controls offered by the window that opens.

  3. In the Image Size section, set the size of the image to create in pixels or another unit. Click the name of the unit to select another unit from the list of available units.

  4. (Optional) To set a different resolution, click Advanced Options, then change the value for Resolution.

    The default resolution of GIMP is usually 72 pixels per inch. This corresponds to a common screen display and is sufficient for most Web page graphics. For print images, use a higher resolution, such as 300 pixels per inch.

    In Color space, select whether the image should be in color (RGB) or Grayscale. For detailed information about image types, see Section 18.6.7, “Image Modes”.

    In Fill With select the color the image is filled with. You can choose between Foreground Color and Background Color set in the toolbox, White or Transparency for a transparent image. Transparency is represented by a gray checkerboard pattern.

  5. When the settings meet your needs, click OK.

18.4.2 Opening an Existing Image

To open an existing image, select File › Open.

In the dialog that opens, select the desired file and click Open.

18.5 Saving and Exporting Images

GIMP makes a distinction between saving and exporting images.

Saving an Image.  The image is stored with all its properties in a lossless format. This includes, for example, layer and path information. This means that repeatedly opening and saving the image will neither degrade its quality nor how well it can be edited.

To save an image, use File › Save or File › Save as. To be able to store all properties, only the native format of GIMP is allowed in this mode: the XCF format.

Exporting an image.  The image is stored in a format in which some properties can be lost. For example, most image formats do not support layers. When exporting, GIMP will often tell you which properties will be lost and ask you to decide how to proceed.

To export an image, use File › Overwrite or File › Export As. Below is a selection of the most common file formats that GIMP can export to:

JPEG

A common format for photographs and Web page graphics without transparency. Its compression method enables reduction of file sizes, but information is lost when compressing. It may be a good idea to use the preview option when adjusting the compression level. Levels of 85% to 75% often result in an acceptable image quality with reasonable compression. Repeatedly opening a JPEG and then saving can quickly result in poor image quality.

GIF

Although very popular in the past for graphics with transparency, GIF is less often used now. GIF is also used for animated images. The format can only save indexed images. See Section 18.6.7, “Image Modes” for information about indexed images. The file size can often be quite small if only a few colors are used.

PNG

With its support for transparency, lossless compression, and good browser support, PNG is the preferred format for Web graphics with transparency. An added advantage is that PNG offers partial transparency, which is not offered by GIF. This enables smoother transitions from colored areas to transparent areas (antialiasing). It also supports the full RGB color space which makes it usable for photos. However, it cannot be used for animations.

18.6 Editing Images

GIMP provides several tools for making changes to images. The functions described here are those most interesting for smaller edits.

18.6.1 Changing the Size of an Image

After an image is scanned or a digital photograph is loaded from the camera, it is often necessary to modify the size for display on a Web page or for printing. Images can easily be made smaller either by scaling them down or by cutting off parts of them.

Enlarging an image is much more problematic. Because of the nature of raster graphics, quality is lost when an image is enlarged. It is recommended to keep a copy of your original image before scaling or cropping.

18.6.1.1 Cropping an Image

  1. Select the crop tool from the toolbox (the paper knife icon) or click Tools › Transform Tools › Crop.

  2. Click a starting corner and drag to outline the area to keep. A rectangle showing the crop area will appear.

  3. To adjust the size of the rectangle, move your mouse pointer above any of the rectangle's sides or corners, then click and drag to resize as desired. If you want to adjust both width and height of the rectangle, use a corner. To adjust only one dimension, use a side. To move the whole rectangle to a different position without resizing, click anywhere near its center and drag to the desired position.

  4. When you are satisfied with the crop area, click anywhere inside to crop the image or press Enter. To cancel the cropping, click anywhere outside the crop area.

18.6.1.2 Scaling an Image

  1. Select Image › Scale Image to change the overall size of an image.

  2. Select the new size by entering it in Width or Height.

    To change the proportions of the image when scaling (this distorts the image), click the chain icon to the right of the fields to break the link between them. When those fields are linked, all values are changed proportionately. Adjust the resolution with X resolution and Y resolution.

    The Interpolation option controls the quality of the resulting image. The default Cubic interpolation method usually is a good standard to use.

  3. When you are finished, click Scale.

18.6.1.3 Changing the Canvas Size

The canvas is the entire visible area of an image. Canvas and image are independent from each other. If the canvas is smaller than the image, you can only see part of the image. If the canvas is larger, you see the original image with extra space around it.

  1. Select Image › Canvas Size.

  2. In the dialog that opens, enter the new size. To make sure the dimensions of the image stay the same, click the chain icon.

  3. After adjusting the size, determine how the existing image should be positioned in comparison to the new size. Use the Offset values or drag the box inside the frame at the bottom.

  4. When you are finished, click Resize.

18.6.2 Selecting Parts of Images

It is often useful to perform an image operation on only part of an image. To do this, the part of the image with which you want to work must be selected. Areas can be selected using the selection tools available in the toolbox, using the quick mask, or combining different options. Selections can also be modified with the items under Select. The selection is outlined with a dashed line, called marching ants.

18.6.2.1 Using the Selection Tools

The main selection tools are easy to use. The more complicated paths tool is not described here.

To determine whether a new selection should replace, be added to, be subtracted from, or intersect with an existing selection, use the Mode row in the tool options.

Rectangle Select

This tool can be used to select rectangular or square areas. To select an area with a fixed aspect ratio, width, height or size, activate the Fixed option and choose the relevant mode in the Tool Options dialog. To create a square, hold Shift while selecting a region.

Ellipse Select

Use this to select elliptical or circular areas. The same options are available as with the rectangular selection. To create a circle, hold Shift while selecting a region.

Free Select (Lasso)

With this tool, you can create a selection based on a combination of freehand drawing and polygonal segments. To draw a freehand line, drag the mouse over the image with the left mouse button pressed. To create a polygonal segment, release the mouse button where the segment should start and press it again where the segment should end. To complete the selection, hover the pointer above the starting point and click inside the circle.

Fuzzy Select (Magic Wand)

This tool selects a continuous region based on color similarities. Set the maximum difference between colors in the tool options dialog in Threshold. By default, the selection is based only on the active layer. To base the selection on all visible layers, check Sample merged.

Select by Color

With this tool, select all the pixels in the image with the same or a similar color as the clicked pixel. The maximum difference between colors can be set in the tool options dialog in Threshold. The important difference between this tool and Fuzzy Select is that Fuzzy Select works on continuous color areas while Select by Color selects all pixels with similar colors in the whole image regardless of their position.

Scissors

Click a series of points in the image. As you click, the points are connected based on color differences. Click the first point to close the area. Convert it to a regular selection by clicking inside it.

Foreground Selection

The Foreground Selection tool lets you semi-automatically select an object in a photograph with minimal manual effort.

To use the Foreground Selection tool, follow these steps:

  1. Activate the Foreground Selection tool by clicking its icon in the Toolbox or choosing Tools › Selection Tools › Foreground Select from the menu.

  2. Roughly select the foreground object you want to extract. Select as little as possible from the background but include the whole object. At this point, the tool works like the Fuzzy Select tool.

    When you release the mouse button, the deselected part of the image is covered with a dark blue mask.

  3. Draw a continuous line through the foreground object going over colors which will be kept for the extraction. Do not paint over background pixels.

    When you release the mouse button, the entire background is covered with a dark blue mask. If parts of the object are also masked, paint over them. The mask will adapt.

  4. When you are satisfied with the mask, press Enter. The mask will be converted to a new selection.

18.6.2.2 Using the Quick Mask

The quick mask is a way of selecting parts of an image using the paint tools. A good way to use it is to first create a rough selection using the Scissors or Free Select tool. Then start using the Quick Mask:

  1. To activate the Quick Mask, in the lower left corner of the image window, click the icon with the dashed box. The Quick Mask icon now changes to a red box.

    The Quick Mask highlights the deselected parts of the image with a red overlay. Areas appearing in their normal color are selected.

    Note
    Note: Changing the Color of the Mask

    To use a different color for displaying the quick mask, right-click the quick mask button then select Configure Color and Opacity from the menu. Click the colored box in the dialog that opens to select a new color.

  2. To modify the selection, use the paint tools.

    Painting with white selects the painted pixels. Painting with black deselects pixels. Shades of gray (colors are treated as shades of gray) create a partial selection. Partial selections allow a smooth transition between selected and deselected areas.

  3. When you are finished, return to the normal selection view by clicking the icon in the lower left corner of the image window. The selection is then displayed with the marching ants.

18.6.3 Applying and Removing Color

Most image editing involves applying or removing color. By selecting a part of the image, you can limit where color can be applied or removed. When you select a tool and move the mouse pointer onto an image, the appearance of the mouse pointer changes to reflect the chosen tool.

With many tools, an icon of the current tool is shown along with the arrow. For paint tools, an outline of the current brush is shown, allowing you to see exactly where you will be painting in the image and how large of an area will be painted.

18.6.3.1 Selecting Colors

The GIMP toolbox always shows two color swatches. The foreground color is used by the paint tools. The background color is used much more rarely, but it can easily be switched to become the foreground color.

  1. To change the color displayed in a swatch, click the swatch. A dialog with five tabs opens.

  2. These tabs provide different color selection methods. Only the first tab, shown in Figure 18.2, “The Basic Color Selector Dialog”, is described here. The new color is shown in Current. The previous color is shown in Old.

    The Basic Color Selector Dialog
    Figure 18.2: The Basic Color Selector Dialog

    The easiest way to select a color is by using the colored areas in the boxes to the left. In the narrow vertical bar, click a color similar to the desired color. The larger box to the left then shows available nuances. Click the desired color. It is then shown in Current.

    The arrow button to the right of Current allows saving colors. Click the arrow to copy the current color to the history. A color can then be selected by clicking it in the history.

    A color can also be selected by directly entering its hexadecimal color code in HTML Notation.

    The color selector defaults to selecting a color by hue. To select by saturation, value, red, green, or blue, select the corresponding radio button to the right. The sliders and number fields can also be used to modify the currently selected color. Experiment a bit to find out what works best for you.

  3. When you are finished, click OK.

To select a color that already exists in your image, use the eye dropper tool. With the tool options, set whether the foreground or background color should be selected.

18.6.3.2 Painting and Erasing

To paint and erase, use the tools from the toolbox. There are a number of options available to fine-tune each tool. Pressure sensitivity options apply only when a pressure-sensitive graphics tablet is used.

The pencil, brush, airbrush, and eraser work much like their real-life equivalents. The ink tool works like a calligraphy pen. Paint by clicking and dragging. The bucket fill is a method of coloring areas of an image. It fills based on color boundaries in the image. Adjusting the threshold modifies its sensitivity to color changes.

18.6.3.3 Adding Text

To add text, use the text tool. Use the tool options to select the desired font and text properties. Click into the image, then start writing.

The text tool creates text in a special layer. To work with the image after adding text, read Section 18.6.6, “Layers”. When the text layer is active, it is possible to modify the text by clicking in the image to reopen the entry dialog.

18.6.3.4 Retouching Images—The Clone Tool

The clone tool is ideal for retouching images. It enables you to paint in an image using information from another part of the image. If desired, it can instead take information from a pattern.

When retouching, use a small brush with soft edges. In this way, the modifications can blend better with the original image.

To select the source point in the image, press and hold Ctrl while clicking the desired source point. Then paint with the tool. When you move the cursor while painting, the source point, marked by a cross, moves as well.

If the Alignment is set to None (the default setting), the source resets to the original when you release the left mouse button.

18.6.4 Adjusting Color Levels

Images often need a little adjusting to get ideal print or display results.

  1. Select Colors › Levels. A dialog opens for controlling the levels in the image.

  2. Good results can usually be obtained by clicking Auto. To make manual adjustments to all channels, use the dropper tools in All Channels to pick areas in the image that should be black, neutral gray, and white.

    To modify an individual channel, select the desired channel in Channel. Then drag the black, white, and middle markers in the slider in Input Levels. You can also use the dropper tools to select points in the image that should serve as the white, black, and gray points for that channel.

    If Preview is checked, the image window shows a preview of the image with the modifications applied.

  3. When you are finished, click OK.

18.6.5 Undoing Mistakes

Most modifications made in GIMP can be undone. To view a history of modifications, use the undo dialog included in the default window layout or open one from the image window menu with Windows › Dockable Dialogs › Undo History.

The dialog shows a base image and a series of editing changes that can be undone. Use the buttons to undo and redo changes. In this way, you can often work back to the base image.

You can also undo and redo changes using Undo and Redo from the Edit menu. Alternatively, use the shortcuts CtrlZ and CtrlY.

18.6.6 Layers

Layers are a very important aspect of GIMP. By drawing parts of your image on separate layers, you can change, move, or delete those parts without damaging the rest of the image.

To understand how layers work, imagine an image created from a stack of transparent sheets. Different parts of the image are drawn on different sheets. The stack can be arranged and sorted. Individual layers or groups of layers can shift position, moving sections of the image to other locations. New sheets can be added and others can be removed or made invisible.

Use the Layers dialog to view the available layers of an image. The text tool automatically creates special text layers when used. The active layer is selected. The buttons at the bottom of the dialog offer several functions. More are available in the menu opened when a layer is right-clicked in the dialog. The two icon spaces before the image name are used for toggling image visibility (eye icon when visible) and for linking layers. Linked layers are marked with the chain icon and moved as a group.

18.6.7 Image Modes

GIMP has three image modes:

  • RGB is a normal color mode and is the best mode for editing most images.

  • Grayscale is used for black-and-white images.

  • Indexed mode limits the colors in the image to a set number. The maximum number of colors in this mode is 255. It is mainly used for GIF images.

If you need an indexed image, it is normally best to edit the image in RGB, then convert to indexed right before exporting. If you export to a format that requires an indexed image, GIMP offers to index the image when exporting.

18.6.8 Special Effects

GIMP includes a wide range of filters and scripts for enhancing images, adding special effects to them or making artistic manipulations. They are available in Filters. Experimenting is the best way to find out what is available.

18.7 Printing Images

To print an image, select File › Print from the image menu. If your printer is configured in the system, it should appear in the list. You can configure printing options on Page Setup and Image Settings tabs.

The Print Dialog
Figure 18.3: The Print Dialog

When you are satisfied with the settings, click Print. Cancel aborts printing.

18.8 For More Information

The following resources are very useful for users of GIMP. They contain much more information about GIMP than this chapter. If you want to use GIMP for more advanced tasks, you should not miss these resources.

  • http://www.gimp.org is the official home page of The GIMP. News about GIMP and related software are regularly posted on the front page.

  • Help provides access to the internal help system including the extensive GIMP User Manual. The package gimp-help needs to be installed. This documentation is also available online in HTML and PDF formats at http://docs.gimp.org. Translations into many languages are available.

  • A collection of many interesting GIMP tutorials is maintained at http://www.gimp.org/tutorials/. It contains basic tutorials for beginners and tutorials for advanced or expert users.

  • Printed books about GIMP are published regularly. You will find a selection of the best ones with short annotations at http://www.gimp.org/books/.

  • GIMP functionality can be extended with scripts and plug-ins. Many such scripts and plug-ins are distributed in the GIMP package, but others can be downloaded from the Internet. At http://registry.gimp.org/, you will find a database of GIMP scripts and plug-ins.

You can also use mailing lists or IRC channels to ask questions about GIMP. Always try to find answers in the documentation mentioned above or in mailing list archives before asking your question. The time of experienced users present on GIMP lists and channels is limited. Be polite and patient. It may take some time before your question is answered.

  • There are several mailing lists about GIMP. You will find them at http://www.gimp.org/mail_lists.html. The GIMP User list is the most appropriate place to ask user questions.

  • There is a whole IRC network dedicated to GIMP and GNOME desktop environment—GIMPNet. You can connect to GIMPNet with your favorite IRC client by pointing it at the irc.gimp.org server. The #gimp-users channel is the right place to ask question about using GIMP. If you want to listen to developer's discussions, join the #gimp channel.

19 GNOME Videos

  • Filename: apps_totem.xml
  • ID: cha.gnome.totem

GNOME Videos is the default movie player. GNOME Videos provides the following multimedia features:

  • Support for a variety of video and audio files

  • A variety of zoom levels and aspect ratios, and a full screen view

  • Seek and volume controls

  • Playlists

  • Complete keyboard navigation

To start GNOME Videos, click Applications › Sound & Video › Videos.

19.1 Using GNOME Videos

When you start GNOME Videos, the following window is displayed.

GNOME Videos Start-Up Window
Figure 19.1: GNOME Videos Start-Up Window

19.1.1 Opening a Video or Audio File

  1. Click Videos › Open.

  2. Select the files you want to open, then click Add

You can also drag a file from another application (such as a file manager) to the GNOME Videos window. GNOME Videos opens the file and plays the movie or song. GNOME Videos displays the title of the movie or song beneath the display area and in the titlebar of the window.

Note
Note: Unrecognized File Format

If you try to open a file format that GNOME Videos does not recognize, the application displays an error message and recommends a suitable codec.

You can double-click a video or audio file in GNOME Files to open it in the GNOME Videos window by default.

19.1.2 Opening a Video or Audio File By URI Location

  1. Click Videos › Open Location.

  2. Specify the URI location of the file you want to open, then click Open.

19.1.3 Playing a DVD, VCD, or CD

To play a DVD, VCD, or CD, insert the disc in the optical device of your computer, then click Movie › Play Disc.

To eject a DVD, VCD, or CD, click Movie › Eject.

To pause a movie or song that is playing, click the GNOME Videos Pause button, or click Movie › Play/Pause. When you pause a movie or song, the statusbar displays Paused and the time elapsed on the current movie or song.

To resume playing a movie or song, click the GNOME Videos Play button, or click Movie › Play/Pause.

To play or pause a movie, you can also press P.

To view properties of a movie or song, click View › Sidebar to make the sidebar appear. The dialog contains the title, artist, year, and duration of movie or song, video dimensions, codec, frame rate, and the audio bit rate.

19.1.4 Seeking Through Movies or Songs

To seek through movies or songs, use any of the following methods:

To skip forward

Click Go › Skip Forward. Alternatively, use .

To skip backward

Click Go › Skip Backward. Alternatively, use .

To move to next movie or song

Click Go › Next Chapter/Movie, or click the GNOME Videos Next button.

To move to previous movie or song

Click Go › Previous Chapter/Movie, or click the GNOME Videos Previous button.

19.1.5 Changing the Zoom Factor

To change the zoom factor of the display area, use any of the following methods:

To zoom to full screen mode

Click View › Fullscreen. Alternatively, press F.

To exit fullscreen mode, click Leave Fullscreen or press Esc.

To zoom to half size (50%) of the original movie or visualization

Click View › Fit Window to Movie › Resize 1:2.

To zoom to size (100%) of the original movie or visualization

Click View › Fit Window to Movie › Resize 1:1.

To zoom to double size (200%) of the original movie or visualization

Click View › Fit Window to Movie  › Resize 2:1.

To switch between different aspect ratios, click View › Aspect Ratio.

The default aspect ratio is Auto.

19.1.6 Showing or Hiding Controls

To hide the window controls of GNOME Videos, click View › Show Controls and deselect the option. To show the controls on the GNOME Videos window, right-click the window, then select Show Controls. If the Show Controls option is selected, GNOME Videos shows the menubar, time elapsed slider, seek control buttons, volume slider, and statusbar on the window. If the Show Controls option is not selected, the application hides these controls and shows only the display area.

19.1.7 Managing Playlists

To show the playlist, click View › Sidebar. The Playlist sidebar is displayed.

You can use the Playlist dialog to do the following:

  • To add a track or movie:  Click the Add button. Select the file you want to add to the playlist, then click OK.

  • To remove a track or movie:  Select the file names from the file name list box, then click Remove.

  • To save a playlist to file:  Click the Save Playlist button, then specify a file name.

  • To move a track or movie up the playlist:  Select the file name from the file name list box, then click the Move Up button.

  • To move a track or movie down the playlist:  Select the file name from the file name list box, then click the Move Down button.

To hide the playlist, click View › Sidebar, or click the Sidebar button.

To enable or disable repeat mode, click Edit › Repeat Mode. To enable or disable shuffle mode, click Edit › Shuffle Mode.

19.1.8 Choosing Subtitles

To choose the language of the subtitles, click View › Subtitles › Select Text Subtitles, then select the subtitles language (DVD) or subtitle file (AVI etc.) you want to display.

To disable the display of subtitles, click View › Subtitles › None.

By default, GNOME Videos chooses the same language for the subtitles that you use on your computer.

GNOME Videos automatically loads and displays subtitles if the file that contains them has the same name as the video file. It supports the following subtitle file extensions: srt, asc, txt, sub, smi, or ssa.

19.2 Modifying GNOME Videos Preferences

To modify GNOME Videos preferences, click Videos › Preferences.

19.2.1 General Preferences

The General Preferences let you select a network connection speed, specify if media files should be played from the last used position, and change the font and encoding used to display subtitles.

GNOME Videos General Preferences
Figure 19.2: GNOME Videos General Preferences

General Preferences include the following:

Playback

Lets you specify whether to start playing the movie from the last position.

Networking

Select network connection speed from the Connection speed drop-down box.

Text Subtitles

Lets you specify whether to load the subtitles automatically, and change the font and encoding used to display the subtitles.

19.2.2 Display Preferences

The Display Preferences let you choose to automatically resize the window when a new video is loaded, change the color balance, and configure visual effects when an audio file is played.

GNOME Videos Display Preferences
Figure 19.3: GNOME Videos Display Preferences

Display Preferences include the following:

Automatically resize the window when a new video is loaded

Select this option if you want GNOME Videos to automatically resize the window when a new video is loaded.

Disable the screen saver when playing video or audio

Select this option if you want GNOME Videos to automatically disable the desktop screen saver while an audio file is playing.

Visual Effects

You can choose to show visual effects when an audio file is playing, select the type of visualization you want to show, and the visualization size.

Color Balance

Specify the level of color brightness, contrast, saturation, and hue.

19.2.3 Audio Preferences

The Audio Preferences dialog lets you select the audio output type.

GNOME Videos Audio Preferences
Figure 19.4: GNOME Videos Audio Preferences

20 Brasero: Burning CDs and DVDs

  • Filename: apps_brasero.xml
  • ID: cha.gnome.burn
Abstract

Brasero is a GNOME program for writing data and audio CDs and DVDs. Start the program from the main menu by clicking Applications › Sound & Video › Brasero.

The following sections are a quick introduction on how to create your own CD or DVD.

20.1 Creating a Data CD or DVD

After starting Brasero for the first time, the main window appears as shown in Figure 20.1.

Main View of Brasero
Figure 20.1: Main View of Brasero

To create a data CD or DVD, proceed as follows:

  1. Click Data project or select Project › New Project › New Data Project. The project view appears.

  2. Drag and drop the desired directories or individual files either from your file manager or by clicking the plus icon. To show your directory structure directly in Brasero, select View › Show Side Panel or press F7.

  3. Optionally, save the project under a name of your choice with Project › Save As.

  4. Name your medium. The original label is Data disc (date).

  5. Choose the output medium from the pull down menu next to the Burn button (CD/DVD or an ISO image file).

  6. Click Burn. A new dialog appears, depending on what medium you have selected in the previous step:

    • CD/DVD.  You can define some parameters, like the burning speed or where to store temporary files. Under Options you can also choose whether to burn the image directly, close the session, verify the written data, and others.

    • ISO Image.  Specify a file name for your ISO image file.

  7. Start the process with Burn.

20.2 Creating an Audio CD

There are no significant differences between creating an audio CD and creating a data CD. Proceed as follows:

  1. Select Project › New Project › New Audio Project.

  2. Drag and drop the individual audio tracks to the project directory. The audio data must be in WAV or Ogg Vorbis format. Determine the sequence of the tracks by moving them up or down in the project directory.

  3. Click Burn. A dialog opens.

  4. Specify a drive to write to.

  5. Click Properties to adjust burning speed and other preferences. When burning audio CDs, choose a lower burning speed to reduce the risk of burn errors.

  6. Click Burn.

20.3 Copying a CD or DVD

To copy a CD or DVD, proceed as follows:

  1. Click Disc Copy or go to Project › New Project › Copy Disc. The Copy CD/DVD dialog opens.

  2. Specify the source drive you want to copy.

  3. Specify a drive or image file to write to.

  4. If necessary, change the burning speed, the temporary directory and other options in Properties.

  5. Click Copy.

20.4 Writing ISO Images

If you already have an ISO image, click Burn image or go to Project › New Project › Burn Image. Choose the image to write and a disc to write to. If necessary, change parameters by clicking Properties. Choose the location of the image file with the pop-up menu labeled Path. Start the burning process and click Burn.

20.5 Creating a Multisession CD or DVD

Multisession discs can be used to write data in more than one burning session. This is useful, for example, for writing backups that are smaller than the media. In each session, you can add another backup file. One note of interest is that you are not only limited to data CDs or DVDs. You can also add audio sessions in a multisession disc.

To start a new multisession disc, do the following:

  1. Start with a data disc first as described in Section 20.1, “Creating a Data CD or DVD”. You cannot start with an audio CD session. Make sure that you do not fill up the entire disc, because otherwise you cannot append a new session.

  2. Click Burn. The window Disc Burning Setup opens.

  3. Select Leave the disc open to add other files later to make the disc multisession capable. Configure other options if needed.

  4. Start the burning session with Burn.

20.6 For More Information

You can find more information about Brasero at https://wiki.gnome.org/Apps/Brasero.

A Help and Documentation

  • Filename: help_user.xml
  • ID: cha.userhelp
Abstract

SUSE® Linux Enterprise Server comes with various sources of information and documentation, many of which are already integrated in your installed system:

Desktop Help Center

The help center of the GNOME desktop (Help) provides central access to the most important documentation resources on your system, in searchable form. These resources include online help for installed applications, man pages, info pages, and the SUSE manuals delivered with your product. Learn more in Section A.1, “Using GNOME Help”.

Separate Help Packages for Some Applications

When installing new software with YaST, the software documentation is installed automatically, and usually appears in the help center of your desktop. However, some applications, such as GIMP, may have different online help packages that can be installed separately with YaST and do not integrate into the help centers.

Documentation in /usr/share/doc

This traditional help directory holds various documentation files and the release notes for your system. Find more detailed information in Section 38.1, “Documentation Directory”.

Man Pages and Info Pages for Shell Commands

When working with the shell, you do not need to know the options of the commands by heart. Traditionally, the shell provides integrated help by means of man pages and info pages. Read more in Section 38.2, “Man Pages” and Section 38.3, “Info Pages”.

A.1 Using GNOME Help

On the GNOME desktop, to start Help directly from an application, either click the Help button or press F1. Both options take you directly to the application's documentation in the help center. However, you can also start Help by opening a terminal end entering yelp or from the main menu by clicking Applications › Favorites › Help.

Main Window of Help
Figure A.1: Main Window of Help

To see an overview of available application manuals, click the menu icon and select All Help.

The menu and the toolbar provide options for navigating the help center, for searching and for printing contents from Help. The help topics are grouped into categories presented as links. Click one of the links to open a list of topics for that category. To search for an item, click the search icon and enter the search string into the search field at the top of the window.

A.2 Additional Help Resources

In addition to the SUSE manuals installed under /usr/share/doc, you can also access the product-specific manuals and documentation on the Web. For an overview of all documentation available for SUSE Linux Enterprise Server check out your product-specific documentation Web page at http://www.suse.com/documentation/.

If you are searching for additional product-related information, you can also refer to the following Web sites:

You can also try general-purpose search engines. For example, use the search terms Linux CD-RW help or LibreOffice file conversion problem if you were having trouble with the CD burning or with LibreOffice file conversion.

A.3 For More Information

Apart from the product-specific help resources, there is a broad range of information available for Linux topics.

A.3.1 The Linux Documentation Project

The Linux Documentation Project (TLDP) is run by a team of volunteers who write Linux-related documentation (see http://www.tldp.org). The set of documents contains tutorials for beginners, but is mainly focused on experienced users and professional system administrators. TLDP publishes HOWTOs, FAQs, and guides (handbooks) under a free license. Parts of the documentation from TLDP is also available on SUSE Linux Enterprise Server.

A.3.1.1 Frequently Asked Questions

FAQs (frequently asked questions) are a series of questions and answers. They originate from Usenet newsgroups where the purpose was to reduce continuous reposting of the same basic questions.

A.3.1.2 Guides

Manuals and guides for various topics or programs can be found at http://www.tldp.org/guides.html. They range from Bash Guide for Beginners to Linux File System Hierarchy to Linux Administrator's Security Guide . Generally, guides are more detailed and exhaustive than HOWTOs or FAQs. They are usually written by experts for experts.

A.3.2 Wikipedia: The Free Online Encyclopedia

Wikipedia is a multilingual encyclopedia designed to be read and edited by anyone (see http://en.wikipedia.org). The content of Wikipedia is created by its users and is published under a dual free license (GFDL and CC-BY-SA). However, as Wikipedia can be edited by any visitor, it should be used only as a starting point or general guide. There is much incorrect or incomplete information in it.

A.3.3 Standards and Specifications

There are various sources that provide information about standards or specifications.

http://www.linux-foundation.org/en/LSB

The Linux Foundation is an independent nonprofit organization that promotes the distribution of free and open source software. The organization endeavors to achieve this by defining distribution-independent standards. The maintenance of several standards, such as the important LSB (Linux Standard Base), is supervised by this organization.

http://www.w3.org

The World Wide Web Consortium (W3C) is one of the best-known standards organizations. It was founded in October 1994 by Tim Berners-Lee and concentrates on standardizing Web technologies. W3C promotes the dissemination of open, license-free, and manufacturer-independent specifications, such as HTML, XHTML, and XML. These Web standards are developed in a four-stage process in working groups and are presented to the public as W3C recommendations (REC).

http://www.oasis-open.org

OASIS (Organization for the Advancement of Structured Information Standards) is an international consortium specializing in the development of standards for Web security, e-business, business transactions, logistics, and interoperability between various markets.

http://www.ietf.org

The Internet Engineering Task Force (IETF) is an internationally active cooperative of researchers, network designers, suppliers, and users. It concentrates on the development of Internet architecture and the smooth operation of the Internet by means of protocols.

Every IETF standard is published as an RFC (Request for Comments) and is available free-of-charge. There are six types of RFC: proposed standards, draft standards, Internet standards, experimental protocols, information documents, and historic standards. Only the first three (proposed, draft, and full) are IETF standards in the narrower sense (see http://www.ietf.org/rfc/rfc1796.txt).

http://www.ieee.org

The Institute of Electrical and Electronics Engineers (IEEE) is an organization that draws up standards in the areas of information technology, telecommunication, medicine and health care, transport, and others. IEEE standards are subject to a fee.

http://www.iso.org

The ISO Committee (International Organization for Standards) is the world's largest developer of standards and maintains a network of national standardization institutes in over 140 countries. ISO standards are subject to a fee.

http://www.din.de , http://www.din.com

The Deutsches Institut für Normung (DIN) is a registered technical and scientific association. It was founded in 1917. According to DIN, the organization is the institution responsible for standards in Germany and represents German interests in worldwide and European standards organizations.

The association brings together manufacturers, consumers, trade professionals, service companies, scientists and others who have an interest in the establishment of standards. The standards are subject to a fee and can be ordered using the DIN home page.

B Documentation Updates

  • Filename: gnome_docupdates.xml
  • ID: app.gnome.docupdates

This chapter lists content changes for this document.

This manual was updated on the following dates:

B.1 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)

General
Bug Fixes

B.2 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)

General
  • The e-mail address for documentation feedback has changed to doc-team@suse.com.

  • The documentation for Docker has been enhanced and renamed to Docker Guide.

Changes for this Guide
  • Book structure: Restructured and merged some sections.

  • Documentation updated from GNOME 3.10 to GNOME 3.20. Minor changes only.

  • Documentation updated for LibreOffice 5.1. Minor changes only. (FATE#320521)

B.3 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)

General
  • SMT Guide is now part of the documentation for SUSE Linux Enterprise Server.

  • Add-ons provided by SUSE have been renamed as modules and extensions. The manuals have been updated to reflect this change.

  • Numerous small fixes and additions to the documentation, based on technical feedback.

  • The registration service has been changed from Novell Customer Center to SUSE Customer Center.

  • In YaST, you will now reach Network Settings via the System group. Network Devices is gone (https://bugzilla.suse.com/show_bug.cgi?id=867809).

Changes for this Guide
Bugfixes
  • Fixed inconsistent terminology referring to the Dash of GNOME Shell (from Doc Comments).

B.4 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)

General
  • Removed all KDE documentation and references because KDE is no longer shipped.

  • Removed all references to SuSEconfig, which is no longer supported (Fate #100011).

  • Move from System V init to systemd (Fate #310421). Updated affected parts of the documentation.

  • YaST Runlevel Editor has changed to Services Manager (Fate #312568). Updated affected parts of the documentation.

  • Removed all references to ISDN support, as ISDN support has been removed (Fate #314594).

  • Removed all references to the YaST DSL module as it is no longer shipped (Fate #316264).

  • Removed all references to the YaST Modem module as it is no longer shipped (Fate #316264).

  • Btrfs has become the default file system for the root partition (Fate #315901). Updated affected parts of the documentation.

  • The dmesg now provides human-readable time stamps in ctime()-like format (Fate #316056). Updated affected parts of the documentation.

  • syslog and syslog-ng have been replaced by rsyslog (Fate #316175). Updated affected parts of the documentation.

  • MariaDB is now shipped as the relational database instead of MySQL (Fate #313595). Updated affected parts of the documentation.

  • SUSE-related products are no longer available from http://download.novell.com but from http://download.suse.com. Adjusted links accordingly.

  • Novell Customer Center has been replaced with SUSE Customer Center. Updated affected parts of the documentation.

  • /var/run is mounted as tmpfs (Fate #303793). Updated affected parts of the documentation.

  • The following architectures are no longer supported: IA64 and x86. Updated affected parts of the documentation.

  • The traditional method for setting up the network with ifconfig has been replaced by wicked. Updated affected parts of the documentation.

  • A lot of networking commands are deprecated and have been replaced by newer commands (usually ip). Updated affected parts of the documentation.

    arp: ip neighbor
    ifconfig: ip addr, ip link
    iptunnel: ip tunnel
    iwconfig: iw
    nameif: ip link, ifrename
    netstat: ss, ip route, ip -s link, ip maddr
    route: ip route
  • Numerous small fixes and additions to the documentation, based on technical feedback.

Changes for This Guide
  • Merged the Application Guide into this guide.

  • Merged the LibreOffice Quick Start into this guide.

  • Documentation updated from GNOME 2 to GNOME 3. Major user interface changes.

SUSE Linux Enterprise Server 12 SP3

AutoYaST

AutoYaST is a system for unattended mass deployment SUSE Linux Enterprise Server systems using an AutoYaST profile containing installation and configuration data. The manual guides you through the basic steps of auto-installation: preparation, installation, and configuration.

Publication Date: April 04, 2018
1 Introduction
1.1 Motivation
1.2 Overview and Concept
2 The Control File
2.1 Introduction
2.2 Format
2.3 Structure
3 Creating A Control File
3.1 Collecting Information
3.2 Using the Configuration Management System (CMS)
3.3 Creating/Editing a Control File Manually
3.4 Creating a Control File via Script with XSLT
4 Configuration and Installation Options
4.1 General Options
4.2 Reporting
4.3 System Registration and Extension Selection
4.4 The Boot Loader
4.5 Partitioning
4.6 iSCSI Initiator Overview
4.7 Fibre Channel over Ethernet Configuration (FCoE)
4.8 Country Settings
4.9 Software
4.10 Upgrade
4.11 Services and Targets
4.12 Network Configuration
4.13 NIS Client
4.14 NIS Server
4.15 LDAP Server (Authentication Server)
4.16 Windows Domain Membership
4.17 Samba Server
4.18 Authentication Client
4.19 NFS Client and Server
4.20 NTP Client
4.21 Mail Configuration
4.22 HTTP Server Configuration
4.23 Squid Server
4.24 FTP Server
4.25 TFTP Server
4.26 Firstboot Workflow
4.27 Security Settings
4.28 Linux Audit Framework (LAF)
4.29 Users and Groups
4.30 Custom User Scripts
4.31 System Variables (Sysconfig)
4.32 Adding Complete Configurations
4.33 Ask the User for Values during Installation
4.34 Kernel Dumps
4.35 DNS Server
4.36 DHCP Server
4.37 SUSE Firewall
4.38 Miscellaneous Hardware and System Components
4.39 Importing SSH Keys and Configuration
4.40 Configuration Management
5 Rules and Classes
5.1 Rules-based Automatic Installation
5.2 Classes
5.3 Mixing Rules and Classes
5.4 Merging of Rules and Classes
6 The Auto-Installation Process
6.1 Introduction
6.2 Choosing the Right Boot Medium
6.3 Invoking the Auto-Installation Process
6.4 System Configuration
7 Running AutoYaST in an Installed System
A Handling Rules
B AutoYaST FAQ - Frequently Asked Questions
C Advanced Linuxrc Options
C.1 Passing parameters to Linuxrc
C.2 info file format
C.3 Advanced Network Setup
D Documentation Updates
D.1 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)
D.2 April 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP2)
D.3 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)
D.4 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)
D.5 February 2015 (Documentation Maintenance Update)
D.6 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)
E GNU Licenses
E.1 GNU Free Documentation License
List of Examples
2.1 AutoYaST Control File (Profile)
2.2 Control file container
2.3 Nested Resources
2.4 Nested Resources with Type Attributes
3.1 Example File for Replacing the Host Name/Domain by Script
4.1 General Options
4.2 Reporting Behavior
4.3 Automated Partitioning
4.4 Detailed Automated Partitioning
4.5 Mount Options
4.6 Keeping partitions
4.7 Auto-detection of partitions to be kept.
4.8 Reading an Existing /etc/fstab
4.9 Create LVM Physical Volume
4.10 LVM Logical Volumes
4.11 RAID1 configuration
4.12 iSCSI client
4.13 FCoE configuration
4.14 Language
4.15 Timezone
4.16 Keyboard
4.17 Package Selection in the Control File with Patterns
4.18 Creating a Package Database With the Additional Package inst-source-utils.rpm
4.19 add_on_products.xml
4.20 Adding SDK product auto AutoYaST configuration file
4.21 Kernel Selection in the Control File
4.22 Package Selection in Control File
4.23 Upgrade and Backup
4.24 Configuring Services and Targets
4.25 Network configuration
4.26 Bridge Interface Configuration
4.27 Network configuration: Proxy
4.28 Inetd Example
4.29 Network configuration: NIS
4.30 NIS Server Configuration
4.31 LDAP configuration
4.32 Samba Client configuration
4.33 Samba Server configuration
4.34 Network configuration: Authentication Client
4.35 Network Configuration: NFS Client
4.36 Network Configuration: NFS Server
4.37 Network configuration: NTP Client
4.38 Mail Configuration
4.39 HTTP Server Configuration
4.40 Squid Server Configuration
4.41 FTP server configuration:
4.42 TFTP server configuration:
4.43 Enabling Firstboot Workflow
4.44 Security configuration
4.45 LAF configuration
4.46 Minimal User Configuration
4.47 Complex User Configuration
4.48 Group Configuration
4.49 Enabling autologin and password-less login
4.50 Script Configuration
4.51 Sysconfig Configuration
4.52 Dumping files into the installed system
4.53 Dumping files into the installed system
4.54 Kdump configuration
4.55 Kdump memory reservation with multiple values
4.56 Basic DNS server settings
4.57 Configuring DNS server zones and advanced settings
4.58 Example dhcp-server section
4.59 Example firewall section
4.60 Printer configuration
4.61 Sound configuration
4.62 Importing SSH Keys and Configuration from /dev/sda2
4.63 Configuring Salt Manager
5.1 Simple Rules File
5.2 Simple Rules File
6.1 Determine HEX code for an IP address
6.2 Linuxrc options in the control file

Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

1 Introduction

AutoYaST is a system for unattended mass deployment of SUSE Linux Enterprise Server systems. AutoYaST installations are performed using an AutoYaST control file (also called profile) with installation and configuration data. That control file can be created using the configuration interface of AutoYaST and can be provided to YaST during installation in different ways.

1.1 Motivation

In an article in issue 78, the Linux Journal (http://www.linuxjournal.com/) writes:

A standard Linux installation asks many questions about what to install, what hardware to configure, how to configure the network interface, etc. Answering these questions once is informative and maybe even fun. But imagine a system engineer who needs to set up a new Linux network with many machines. Now, the same issues need to be addressed and the same questions answered repeatedly. This makes the task very inefficient, not to mention a source of irritation and boredom. Hence, a need arises to automate this parameter and option selection.

The thought of simply copying the hard disks naturally crosses one's mind. This can be done quickly, and all the necessary functions and software will be copied without option selection. However, the fact is that simple copying of hard disks causes the individual computers to become too similar. This, in turn, creates an altogether new mission of having to reconfigure the individual settings on each PC. For example, IP addresses for each machine will need to be reset. If this is not done properly, strange and inexplicable behavior results.

A regular installation of SUSE Linux Enterprise Server is semi-automated by default. The user is prompted to select the necessary information at the beginning of the installation (usually language only). YaST then generates a proposal for the underlying system depending on different factors and system parameters. Usually—and especially for new systems—such a proposal can be used to install the system and provides a usable installation. The steps following the proposal are fully automated.

AutoYaST can be used where no user intervention is required or where customization is required. Using an AutoYaST control file, YaST prepares the system for a custom installation and does not interacts with the user, unless specified in the file controlling the installation.

AutoYaST is not an automated GUI system. This means that usually many screens will be skipped—you will never see the language selection interface, for example. AutoYaST will simply pass the language parameter to the sub-system without displaying any language related interface.

1.2 Overview and Concept

Using AutoYaST, multiple systems can easily be installed in parallel and quickly. They need to share the same environment and similar, but not necessarily identical, hardware. The installation is defined by an XML configuration file (usually named autoinst.xml) called the AutoYaST control file. It can initially be created using existing configuration resources easily be tailored for any specific environment.

AutoYaST is fully integrated and provides various options for installing and configuring a system. The main advantage over other auto-installation systems is the possibility to configure a computer by using existing modules and avoiding using custom scripts which are normally executed at the end of the installation.

This document will guide you through the three steps of auto-installation:

  • Preparation: All relevant information about the target system is collected and turned into the appropriate directives of the control file. The control file is transferred onto the target system where its directives will be parsed and fed into YaST.

  • Installation: YaST performs the installation of the basic system using the data from the AutoYaST control file.

  • Configuration: After the installation of the basic system, the system configuration is performed in the second stage of the installation. User defined post-installation scripts from the AutoYaST control file will also be executed at this stage.

Note
Note: Second Stage

A regular installation of SUSE Linux Enterprise Server 12 SP3 is performed in a single stage. The auto-installation process, however, is divided into two stages. After the installation of the basic system the system boots into the second stage where the system configuration is done.

The second stage can be turned off with the second_stage parameter:

<general>
  <mode>
    <confirm config:type="boolean">false</confirm>
    <second_stage config:type="boolean">false</second_stage>
  </mode>
</general>

The complete and detailed process is illustrated in the following figure:

Auto-installation process
Figure 1.1: Auto-installation process

2 The Control File

2.1 Introduction

The control file usually is a configuration description for a single system. It consists of sets of resources with properties including support for complex structures such as lists, records, trees and large embedded or referenced objects.

Important
Important: Control Files from Previous Releases are Incompatible

A lot of major changes were introduced with SUSE Linux Enterprise Server 12 SP3 (the switch to systemd and GRUB 2 for example). These changes also required fundamental changes in AutoYaST, therefore you cannot use AutoYaST control files created on previous SUSE Linux Enterprise Server versions to install SUSE Linux Enterprise Server 12 SP3 and vice versa.

2.2 Format

The XML configuration format provides a consistent file structure, which is easy to learn and to remember when attempting to configure a new system.

The AutoYaST control file uses XML to describe the system installation and configuration. XML is a commonly used markup, and many users are familiar with the concepts of the language and the tools used to process XML files. If you edit an existing control file or create a control file using an editor from scratch, it is strongly recommended to validate the control file. This can be done using a validating XML parser such as xmllint or jing, for example (see Section 3.3, “Creating/Editing a Control File Manually”).

The following example shows a control file in XML format:

Example 2.1: AutoYaST Control File (Profile)
<?xml version="1.0"?>
<!DOCTYPE profile>
<profile
  xmlns="http://www.suse.com/1.0/yast2ns"
  xmlns:config="http://www.suse.com/1.0/configns">
  <partitioning  config:type="list">
    <drive>
      <device>/dev/sda</device>
      <partitions config:type="list">
        <partition>
          <filesystem config:type="symbol">btrfs</filesystem>
          <size>10G</size>
          <mount>/</mount>
        </partition>
        <partition>
          <filesystem config:type="symbol">xfs</filesystem>
          <size>120G</size>
          <mount>/data</mount>
        </partition>
      </partitions>
    </drive>
  </partitioning>
  <scripts>
    <pre-scripts>
      <script>
        <interpreter>shell</interpreter>
        <filename>start.sh</filename>
        <source>
        <![CDATA[
#!/bin/sh
echo "Starting installation"
exit 0

]]>

        </source>
      </script>
    </pre-scripts>
  </scripts>
</profile>

2.3 Structure

Below is an example of a basic control file container, the actual content of which is explained later on in this chapter.

Example 2.2: Control file container
<?xml version="1.0"?>
<!DOCTYPE profile>
<profile
  xmlns="http://www.suse.com/1.0/yast2ns"
  xmlns:config="http://www.suse.com/1.0/configns">
  <!-- RESOURCES -->
</profile>

The <profile> element (root node) contains one or more distinct resource elements. The permissible resource elements are specified in the schema files

2.3.1 Resources and Properties

A resource element either contains multiple and distinct property and resource elements, or multiple instances of the same resource element, or it is empty. The permissible content of a resource element is specified in the schema files.

A property element is either empty or contains a literal value. The permissible property elements and values in each resource element are specified in the schema files

An element can be either a container of other elements (a resource) or it has a literal value (a property); it can never be both. This restriction is specified in the schema files. A configuration component with more than one value must either be represented as an embedded list in a property value or as a nested resource.

2.3.2 Nested Resources

Nested resource elements allow a tree-like structure of configuration components to be built to any level.

Example 2.3: Nested Resources
...
<drive>
  <device>/dev/sda</device>
  <partitions> <!-- this is wrong, explanation below -->
    <partition>
      <size>10G</size>
      <mount>/</mount>
    </partition>
    <partition>
      <size>1G</size>
      <mount>/tmp</mount>
    </partition>
  </partitions>
</drive>
....

In the example above the disk resource consists of a device property and a partitions resource. The partitions resource contains multiple instances of the partition resource. Each partition resource contains a size and mount property.

The XML schema defines the partitions element as a resource supporting one or multiple partition element children. If only one partition resource is specified, it is important to use the config:type attribute of the partitions element to indicate that the content is a resource, in this case a list. Using the partitions element without specifying the type in this case will result in undefined behavior, as YaST will incorrectly interpret the partitions resource as a property. The example below illustrates this use case.

Example 2.4: Nested Resources with Type Attributes
...
<drive>
  <device>/dev/sda</device>
  <partitions config:type="list">
     <partition>
        <size>10G</size>
        <mount>/</mount>
     </partition>
     <partition>
        <size>1G</size>
        <mount>/tmp</mount>
     </partition>
  </partitions>
</drive>
....

2.3.3 Attributes

Global attributes are used to define metadata on resources and properties. Attributes are used to define context switching. They are also used for naming and typing properties as shown in the previous sections. Attributes are in a separate namespace so they do not need to be treated as reserved words in the default namespace.

Global attributes are defined in the configuration namespace and must always be prefixed with config: . All attributes are optional. Most can be used with both resource and property elements but some can only be used with one type of element which is specified in the schema files.

The type of an element is defined using the config:type attribute. The type of a resource element is always RESOURCE, although this can also be made explicit with this attribute (to ensure correct identification of an empty element, for example, when there is no schema file to refer to). A resource element cannot be any other type and this restriction is specified in the schema file. The type of a property element determines the interpretation of its literal value. The type of a property element defaults to STRING, as specified in the schema file. The full set of permissible types is specified in the schema file.

3 Creating A Control File

3.1 Collecting Information

To create the control file, you need to collect information about the systems you are going to install. This includes hardware data and network information among other things. Make sure you have the following information about the machines you want to install:

  • Hard disk types and sizes

  • Graphical interface and attached monitor, if any

  • Network interface and MAC address if known (for example, when using DHCP)

3.2 Using the Configuration Management System (CMS)

To create the control file for one or more computers, a configuration interface based on YaST is provided. This system depends on existing modules which are usually used to configure a computer in regular operation mode, for example, after SUSE Linux Enterprise Server is installed.

The configuration management system lets you easily create control files and manage a repository of configurations for the use in a networked environment with multiple clients.

Configuration System
Figure 3.1: Configuration System

3.2.1 Creating a New Control File

With some exceptions, almost all resources of the control file can be configured using the configuration management system. The system offers flexibility and the configuration of some resources is identical to the one available in the YaST control center. In addition to the existing and familiar modules new interfaces were created for special and complex configurations, for example for partitioning, general options and software.

Furthermore, using a CMS guarantees the validity of the resulting control file and its direct use for starting automated installation.

Make sure the configuration system is installed (package autoyast2) and call it using the YaST control center or as root with the following command (make sure the DISPLAY variable is set correctly to start the graphical user interface instead of the text-based one):

/sbin/yast2 autoyast

3.3 Creating/Editing a Control File Manually

If editing the control file manually, make sure it has a valid syntax. To check the syntax, use the tools already available on the distribution. For example, to verify that the file is well-formed (has a valid XML structure), use the utility xmllint available with the libxml2 package:

xmllint <control file>

If the control file is not well formed, for example, if a tag is not closed, xmllint will report the errors.

To validate the control file, use the tool jing from the package with the same name. During validation misplaced or missing tags and attributes and wrong attribute values are detected. the package jing is provided with the SUSE Software Development Kit.

jing /usr/share/YaST2/schema/autoyast/rng/profile.rng <control file>

/usr/share/YaST2/schema/autoyast/rng/profile.rng is provided by the package yast2-schema. This file describes the syntax and classes of an AutoYaST profile.

Before going on with the autoinstallation, fix any errors resulting from such checks. The autoinstallation process cannot be started with an invalid and not well-formed control file.

You can use any XML editor available on your system or any text editor with XML support (for example, Emacs, Vim). However, it is not optimal to create the control file manually for many machines and it should only be seen as an interface between the autoinstallation engine and the Configuration Management System (CMS).

Tip
Tip: Using Emacs as an XML Editor

The built-in nxml-mode turns Emacs into a fully-fledged XML editor with automatic tag completion and validation. Refer to the Emacs help for instructions on how to set up nxml-mode.

3.4 Creating a Control File via Script with XSLT

If you have a template and want to change a few things via script or command line, use an XSLT processor like xsltproc. For example, if you have an AutoYaST control file and want to fill out the host name via script for any reason (if doing this so often, you want to script it)

First, create an XSL file

Example 3.1: Example File for Replacing the Host Name/Domain by Script
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:y2="http://www.suse.com/1.0/yast2ns"
  xmlns:config="http://www.suse.com/1.0/configns"
  xmlns="http://www.suse.com/1.0/yast2ns"
  version="1.0">
  <xsl:output method="xml" encoding="UTF-8" indent="yes" omit-xml-declaration="no" cdata-section-elements="source"/>

  <!-- the parameter names -->
  <xsl:param name="hostname"/>
  <xsl:param name="domain"/>

  <xsl:template match="/">
    <xsl:apply-templates select="@*|node()"/>
  </xsl:template>

  <xsl:template match="y2:dns">
    <xsl:copy>
      <!-- where to copy the parameters -->
      <domain><xsl:value-of select="string($domain)"/></domain>
      <hostname><xsl:value-of select="string($hostname)"/></hostname>
      <xsl:apply-templates select="@*|node()"/>
    </xsl:copy>
  </xsl:template>


  <xsl:template match="@*|node()" >
    <xsl:copy>
      <xsl:apply-templates select="@*|node()"/>
    </xsl:copy>
  </xsl:template>

</xsl:stylesheet>

This file expects the host name and the domain name as parameters from the user.

<xsl:param name="hostname"/>
<xsl:param name="domain"/>

There will be a copy of those parameters in the dns section of the control file. That means, if there already is a domain element in the dns section, you will get a second one which is not good.

For more information about XSLT, go to the official Web page www.w3.org/TR/xslt

4 Configuration and Installation Options

This chapter introduces important parts of a control file for standard purposes. To learn about other available options, use the configuration management system.

Note that for some configuration options to work, additional packages need to be installed, depending on the software selection you have configured. If you choose to install a minimal system then some packages might be missing and need to be added to the individual package selection.

YaST will install packages required in the second phase of the installation and before the post-installation phase of AutoYaST has started. However, if necessary YaST modules are not available in the system, important configuration steps will be skipped. For example, no security settings will be configured if yast2-security is not installed.

4.1 General Options

General options include all the settings related to the installation process and the environment of the installed system.

The mode section configures the behavior of AutoYaST with regard to confirmation and rebooting. The following needs to be in the <general><mode> section.

By default, the user must confirm the auto-installation process. This option allows the user to view and change the settings for a target system before they are committed and can be used for debugging. confirm is set to true by default to avoid recursive installs when the system schedules a reboot after initial system setup. Only disable confirmation if you want to carry out a fully unattended installation.

With halt you cause AutoYaST to shut down the machine after all packages have been installed. Instead of a reboot into stage two, the machine is turned off. The boot loader is already installed and all your chroot scripts have run.

final_halt and final_reboot halts or reboots the machine after the installation and the configuration are finished at the end of stage 2.

final_restart_services: After installation and configuration are finished at the end of stage 2 all services will be restarted by default. With this flag set to false no restart will be done.

activate_systemd_default_target: After installation and configuration are finished at the end of stage 2 the default target system will be activated.

ntp_sync_time_before_installation specifies the NTP server with which the system time needs to be synchronized before starting the installation on the target system. It will not be synchronized if this flag has not been used. Keep in mind that you need a reachable NTP server and network connections while running the installation.

max_systemd_wait specifies how long AutoYaST waits at most for systemd to set up the default target. Normally you do not need to bother with this entry. If it is not preset, a reasonable default (30 seconds) is used.

Some openSUSE versions use the kexec feature and do not reboot anymore between stage 1 and stage 2. With the forceboot option you can force the reboot in case you need it for some reason. The value true will reboot, false will not reboot and a missing forceboot option uses the product's default.

Attribute

Values

Description

confirm

If this boolean is set to true, the installation stops at the confirmation screen (also called proposal screen) and needs to be confirmed with the Install button.

<confirm config:type="boolean">
  true
</confirm>

Optional. The default is true.

halt

Shuts down the machine after the first stage. So if you turn it on again, the machine boots and the second stage of the autoinstallation starts.

<halt config:type="boolean">
  true
</halt>

Optional. The default is false.

second_stage

This boolean determines if AutoYaST will run in the second stage too (after the partitioning, software and boot loader installation of the first stage). If you set this to false, a normal manual installation happens in the second stage.

<second_stage config:type="boolean">
  true
</second_stage>

Optional. The default is true.

final_reboot

If you set this to true, the machine will reboot at the very end of the installation (when everything is installed and configured at the end of the second stage).

<final_reboot config:type="boolean">
  true
</final_reboot>

Optional. The default is false. It makes no sense to set this and final_halt to true.

final_halt

If you set this to true, the machine will shut down at the very end of the installation (when everything is installed and configured at the end of the second stage).

<final_halt config:type="boolean">
  true
</final_halt>

Optional. The default is false. It makes no sense to set this and final_reboot to true.

confirm_base_product_license

If you set this to true, the EULA of the base product will be shown. The user needs to accept this license. Otherwise the installation will be canceled.

<confirm_base_product_license config:type="boolean">
  true
</confirm_base_product_license>

Optional. The default is false. This applies to the base product license only. Use the flag confirm_license in the add-on section to show additional licenses.

final_restart_services

If you set this entry to false, all services will not be restarted at the very end of the installation (when everything is installed and configured at the end of the second stage).

<final_restart_services config:type="boolean">
  false
</final_restart_services>

Optional. The default is true.

activate_systemd_default_target

If you set this entry to false, the default target will not be activated via the call systemctl isolate.

<activate_systemd_default_target config:type="boolean">
  false
</activate_systemd_default_target>

Optional. The default is true.

forceboot

Some openSUSE releases use kexec to avoid the reboot after the first stage. They immediately boot into the installed system. You can force a reboot with this:

<forceboot config:type="boolean">
  true
</forceboot>

Optional. The default is false.

self_update

This option allows to enable (set to true) or disable (set to false the self-update. Check out Section 6.4, “Installer Self-Update” to find further information about this feature.

<self_update config:type="boolean">
  false
<self_update/>

Alternatively, you can specify the boot parameter self_update on the kernel command line.

Optional. The default is true.

self_update_url

Location of the update repository to use during YaST self-update. Check out the Deployment Guide to find further information about this feature.

Important
Important: Installer Self-Update Repository Only

The self_update_url parameter expects only the installer self-update repository URL. Do not supply any other repository URL—for example the URL of the software update repository.

<self_update_url>
  http://example.com/updates/$arch
</self_update_url>

Alternatively, you can specify the boot parameter self_update on the kernel command line.

The URL can contain a variable $arch that will be replaced by the system's architecture, such as x86_64, s390x, etc.

Use the boot parameter self_update=1 to enable the YaST self-update.

 

AutoYaST allows you to configure the proposal screen with the <proposals config:type="list"> option in the control file. All proposals that are listed in that section are shown in the proposal screen if you set the confirm option to true. Proposals are also used during the regular installation and can be found in the file control.xml in the root directory of the installation media.

Example 4.1: General Options
<general>
  <signature-handling>
    <accept_unsigned_file config:type="boolean">true</accept_unsigned_file>
    <accept_file_without_checksum config:type="boolean">true</accept_file_without_checksum>
    <accept_verification_failed config:type="boolean">true</accept_verification_failed>
    <accept_unknown_gpg_key config:type="boolean">true</accept_unknown_gpg_key>
    <import_gpg_key config:type="boolean">true</import_gpg_key>
    <accept_non_trusted_gpg_key config:type="boolean">true</accept_non_trusted_gpg_key>
    </signature-handling>
    <cio_ignore config:type="boolean">false</cio_ignore>       <! -- IBM z Systems only -->
  <mode>
    <halt config:type="boolean">false</halt>
    <forceboot config:type="boolean">false</forceboot>
    <final_reboot config:type="boolean">false</final_reboot>
    <final_halt config:type="boolean">false</final_halt>
    <confirm_base_product_license config:type="boolean">false</confirm_base_product_license>
    <confirm config:type="boolean">true</confirm>
    <second_stage config:type="boolean">true</second_stage>
  </mode>
  <self_update_url>http://example.com/updates/$arch<self_update_url/>
  <proposals config:type="list">
    <proposal>partitions_proposal</proposal>
  </proposals>
  <wait>
    <pre-modules config:type="list">
      <module>
        <name>networking</name>
        <sleep>
          <time config:type="integer">10</time>
          <feedback config:type="boolean">true</feedback>
        </sleep>
        <script>
          <source>sleep 5</source>
          <debug config:type="boolean">false</debug>
        </script>
      </module>
    </pre-modules>
    <post-modules config:type="list">
      <module>
        <name>networking</name>
        <sleep>
          <time config:type="integer">3</time>
          <feedback config:type="boolean">true</feedback>
        </sleep>
        <script>
          <source>sleep 7</source>
          <debug config:type="boolean">false</debug>
        </script>
      </module>
    </post-modules>
  </wait>
  <storage>
    <!--
       partition_alignment:
         align_optimal  - That is the default. Partitions are aligned like the
                          kernel suggests. This can lead to problem with some
                          machines/bioses that are unable to boot with that
                          alignment
         align_cylinder -  Partitions always start on a cylinder boundary
    -->
     <partition_alignment config:type="symbol">align_cylinder</partition_alignment>
  </storage>
</general>

You can let AutoYaST sleep before and after each module run during the second stage. You can run scripts and/or pass a value (in seconds) for AutoYaST to sleep. In the example above AutoYaST will sleep for 15 seconds (10+5) before the network configuration starts and 10 seconds (3+7) after the network configuration is done. The scripts in the example do not really make a lot of sense because you could pass that value as time value too. They are only used to show how scripts in the wait section work now.

To blacklist devices, use the flag cio_ignore. This option is available on IBM z Systems only.

Tip
Tip: Enabling Multipath for the Installation

When installing on a network storage that is accessed via multiple paths, you need to enable multipath for the installation with the start_multipath parameter. This parameter must be placed within the following XML structure:

<general>
  <storage>
    <start_multipath config:type="boolean">true</start_multipath>
  </storage>
</general>

Alternatively, you can pass the following parameter to linuxrc: LIBSTORAGE_MULTIPATH_AUTOSTART=ON

Tip
Tip: Handling Installer Self-Update Signatures

Installer updates are delivered using a dedicated repository, so the same security checks that are applied to other repositories and packages are performed on these updates.

The section /general/signature_handling can be used to specify a different behavior.

<general>
  <signature-handling>
    <accept_unknown_gpg_key config:type="boolean">true</accept_unknown_gpg_key>
  </signature-handling>
</general>

4.2 Reporting

The report resource manages three types of pop-ups that may appear during installation:

  • message pop-ups (usually non-critical, informative messages),

  • warning pop-ups (if something might go wrong),

  • error pop-ups (in case an error occurs).

Example 4.2: Reporting Behavior
<report>
  <errors>
    <show config:type="boolean">true</show>
    <timeout config:type="integer">0</timeout>
    <log config:type="boolean">true</log>
  </errors>
  <warnings>
    <show config:type="boolean">true</show>
    <timeout config:type="integer">10</timeout>
    <log config:type="boolean">true</log>
  </warnings>
  <messages>
    <show config:type="boolean">true</show>
    <timeout config:type="integer">10</timeout>
    <log config:type="boolean">true</log>
  </messages>
  <yesno_messages>
    <show config:type="boolean">true</show>
    <timeout config:type="integer">10</timeout>
    <log config:type="boolean">true</log>
  </yesno_messages>
</report>

Depending on your experience, you can skip, log and show (with timeout) those messages. It is recommended to show all messages with timeout. Warnings can be skipped in some places but should not be ignored.

The default setting in auto-installation mode is to show errors without timeout and to show all warnings/messages with a timeout of 10 seconds.

Warning
Warning: Critical System Messages

Note that not all messages during installation are controlled by the report resource. Some critical messages concerning package installation and partitioning will show up ignoring your settings in the report section. Usually those messages will need to be answered with Yes or No.

4.3 System Registration and Extension Selection

Registering the system with the can be configured within the suse_register resource. The following example registers the system with the SUSE Customer Center. In case your organization provides its own registration server, you need to specify the required data with the reg_server* properties. Refer to the table below for details.

<suse_register>
  <do_registration config:type="boolean">true</do_registration>
  <email>tux@example.com</email>
  <reg_code>MY_SECRET_REGCODE</reg_code>
  <install_updates config:type="boolean">true</install_updates>
  <slp_discovery config:type="boolean">false</slp_discovery>
</suse_register>

As an alternative to the fully automated registration, AutoYaST can also be configured to start the YaST registration module during the installation. this offers the possibility to enter the registration data manually. The following XML code is required:

<general>
 <semi-automatic config:type="list">
   <semi-automatic_entry>scc</semi-automatic_entry>
 </semi-automatic>
</general>
Tip
Tip: Using the Installation Network Settings

In case you need to use the same network settings that were used for the installation, AutoYaST needs to run the network setup in stage 1 right before the registration is started:

<networking>
  <setup_before_proposal config:type="boolean">true</setup_before_proposal>
</networking>

Element

Description

Comment

do_registration

Boolean

<do_registration config:type="boolean"
>true</do_registration>

Specify whether the system should be registered or not. If set to false all other options are ignored and the system is not registered.

e-mail

E-mail address

<email>tux@example.com</email>

Optional. The e-mail address matching the registration code.

reg_code

Text

<reg_code>SECRET_REGCODE</reg_code>

Required. Registration code.

install_updates

Boolean

<install_updates config:type="boolean"
>true</install_updates>

Optional. Determines if updates from the Updates channels should be installed. The default value is to not install them (false).

slp_discovery

Boolean

<slp_discovery config:type="boolean"
>true</slp_discovery>

Optional. Search for a registration server via SLP. The default value is false.

Expects to find a single server. If more than one server is found, the installation will fail. In case there is more than one registration server available, you need to specify one with reg_server.

If neither slp_discovery nor reg_server are set, the system is registered with the SUSE Customer Center.

This setting also affects the self-update feature: If it is disabled, no SLP search will be performed.

reg_server

URL

<reg_server>
  https://smt.example.com
</reg_server>

Optional. SMT server URL. If neither slp_discovery nor reg_server are set, the system is registered with the SUSE Customer Center.

The SMT server is queried for a URL of the self-update repository. So if self_update_url is not set, the SMT server influences where the self-updates are downloaded from. Check out the Deployment Guide to find further information about this feature.

reg_server_cert_fingerprint_type

SHA1 or SHA256

<reg_server_cert_fingerprint_type>
  SHA1
</reg_server_cert_fingerprint_type>

Optional. Requires a checksum value provided with reg_server_cert_fingerprint. Using the fingerprint is recommended, since it ensures the SSL certificate is verified. The matching certificate will be automatically imported when the SSL communication fails because of a verification error.

reg_server_cert_fingerprint

Server Certificate Fingerprint value in hexadecimal notion (case-insensitive).

<reg_server_cert_fingerprint>
  01:AB...:EF
</reg_server_cert_fingerprint>

Optional. Requires a fingerprint type value provided with reg_server_cert_fingerprint_type. Using the fingerprint is recommended, since it ensures the SSL certificate is verified. The matching certificate will be automatically imported when the SSL communication fails because of a verification error.

reg_server_cert

URL

<reg_server_cert>
  http://smt.example.com/smt.crt
</reg_server_cert>

Optional. URL of the SSL certificate on the server. Using this option is not recommended, since the certificate that is downloaded is not verified. Use reg_server_cert_fingerprint instead.

addons

Add-ons list

Specify an extension from the registration server that should be added to the installation repositories. See Section 4.3.1, “Extensions” for details.

Tip
Tip: Creating Own Server Certificate Fingerprint

In order to generate a new Server Certificate Fingerprint for the entry reg_server_cert_fingerprint you can use the following command:

echo | openssl s_client -showcerts -connect scc.suse.com:443 2> /dev/null |
openssl x509 -noout -fingerprint -sha256

Replace scc.suse.com with your server, optionally use -sha1 instead of -sha256 (but the SHA256 default is better).

NOTE: This can be used in a trusted network only! In a non-trusted network (or over Internet) you should get the fingerprint directly on the server. Or verify that the downloaded certificate is exactly as on the server.

4.3.1 Extensions

The SUSE Customer Center provides several extensions, such as sle-sdk (Software Development Kit - SDK) that can be included as additional sources during the installation. Adding extensions can be done via the addons property within the suse_register block.

Note
Note: Availability of Extensions

The availability of extensions is product and architecture dependent. Not all extensions are available on other architectures. The only extension available for SUSE Linux Enterprise Desktop is the sle-sdk.

Some extensions, such as the sle-we, sle-ha and sle-ha-geo require a registration code.

With SUSEConnect --list-extensions (available since SLES 12 SP1), you can list all available extensions in a registered system. The result looks like:

Install with: SUSEConnect -p sle-sdk/12.2/x86_64

The -p argument displays the NAME/VERSION/ARCH values that can be used in the AutoYaST profile as follows:

<addons config:type="list">
 <addon>
  <!-- SUSE Linux Enterprise Software Development Kit -->
  <name>sle-sdk</name>
  <version>12.2</version>
  <arch>x86_64</arch>
 </addon>
</addons>

For background information and add-on listings for SLES 12, 12 SP1, and 12 SP2, see https://github.com/yast/yast-registration/wiki/Available-SCC-Extensions-for-Use-in-Autoyast. The listings will get updated from time to time.

4.4 The Boot Loader

This documentation is for yast2-bootloader and applies to GRUB 2. For older product versions shipping with legacy GRUB, refer to the documentation that comes with your distribution in /usr/share/doc/packages/autoyast2/

The general structure of the AutoYaST boot loader part looks like the following:

<bootloader>
  <loader_type>
    <!-- boot loader type (grub2 or grub2-efi) -->
  </loader_type>
  <global>
    <!--
      entries defining the installation settings for GRUB 2 and
      the generic boot code
    -->
  </global>
  <device_map config:type="list">
    <!-- entries defining the order of devices -->
  </device_map>
 </bootloader>

4.4.1 Loader Type

Define which boot loader to use: grub2 or grub2-efi.

<loader_type>grub2</loader_type>

4.4.2 Globals

This is an important if optional part. Define here where to install GRUB 2 and how the boot process will work. Again, yast2-bootloader proposes a configuration if you do not define one. Usually the AutoYaST control file includes only this part and all other parts are added automatically during installation by yast2-bootloader. Unless you have some special requirements, do not specify the boot loader configuration in the XML file.

<global>
  <activate config:type="boolean">true</activate>
  <timeout config:type="integer">10</timeout>
  <suse_btrfs config:type="boolean">true</suse_btrfs>
  <terminal>gfxterm</terminal>
  <gfxmode>1280x1024x24</gfxmode>
</global>

Attribute

Description

activate

Set the boot flag on the boot partition. The boot partition can be / if there is no separate /boot partition. If the boot partition is on a logical partition, the boot flag is set to the extended partition.

<activate config:type="boolean">true</activate>

append

Kernel parameters added at the end of boot entries for normal and recovery mode.

<append>nomodeset vga=0x317</append>

boot_boot

Write GRUB 2 to a separate /boot partition. If no separate /boot partition exists, GRUB 2 will be written to /.

<boot_boot>false</boot_boot>

boot_custom

Write GRUB 2 to a custom device.

<boot_custom>/dev/sda3</boot_custom>

boot_extended

Write GRUB 2 to the extended partition (important if you want to use a generic boot code and the /boot partition is logical). NOTE: if the boot partition is logical, you should use boot_mbr (write GRUB 2 to MBR) rather than generic_mbr.

<boot_extended>false</boot_extended>

boot_mbr

Write GRUB 2 to MBR of the first disk in the order (device.map includes order of disks).

<boot_mbr>false</boot_mbr>

boot_root

Write GRUB 2 to / partition.

<boot_root>false</boot_root>

generic_mbr

Write generic boot code to MBR, will be ignored if boot_mbr is set to true.

<generic_mbr config:type="boolean">false</generic_mbr>

gfxmode

Graphical resolution of the GRUB 2 screen (requires <terminal> to be set to gfxterm. Valid entries are auto, HORIZONTALxVERTICAL, or HORIZONTALxVERTICALxCOLOR DEPTH. You can see the screen resolutions supported by GRUB 2 on a particular system by using the vbeinfo command at the GRUB 2 command line in the running system.

<gfxmode>1280x1024x24</gfxmode>

os_prober

If set to true, automatically searches for operating systems already installed and generates boot entries for them during the installation

<os_prober config:type="boolean">false</os_prober>

suse_btrfs

If set to true, booting from Btrfs snapshots will be enabled.

<suse_btrfs config:type="boolean">false</suse_btrfs>

serial

Command to execute if the GRUB 2 terminal mode is set to serial.

<serial>
  serial --speed=115200 --unit=0 --word=8 --parity=no --stop=1
</serials>

terminal

Specify the GRUB 2 terminal mode to use, Valid entries are console, gfxterm, and serial. If set to serial, the serial command needs to be specified with <serial>, too.

<terminal>serial</terminal>

timeout

The timeout in seconds until the default boot entry is booted automatically.

<timeout config:type="integer">10</timeout>

vgamode

Adds the kernel parameter vga=VALUE to the boot entries.

<vgamode>0x317</vgamode>

xen-append

Kernel parameters added at the end of boot entries for Xen guests.

<append>nomodeset vga=0x317</append>

xen-kernel-append

Kernel parameters added at the end of boot entries for Xen kernels on the VM Host Server.

<xen-append>dom0_mem=768M</xen-append>

4.4.3 Device map

GRUB 2 avoids mapping problems between BIOS drives and Linux devices by using device ID strings (UUIDs) or file system labels when generating its configuration files. GRUB 2 utilities create a temporary device map on the fly, which is usually sufficient, particularly on single-disk systems. However, if you need to override the automatic device mapping mechanism, create your custom mapping in this section.

<device_map config:type="list">
  <device_map_entry>
    <firmware>hd0</firmware> <!-- order of devices in target map  -->
    <linux>/dev/disk/by-id/ata-ST3500418AS_6VM23FX0</linux> <!-- name of device (disk)  -->
  </device_map_entry>
</device_map>

4.5 Partitioning

4.5.1 Drive Configuration

The elements listed below must be placed within the following XML structure:

<profile>
  <partitioning config:type="list">
    <drive>
     ...
    </drive>
  </partitioning>
</profile>

Attribute

Values

Description

device

The device you want to configure in this <drive> section. You can use persistent device names via id, like /dev/disk/by-id/ata-WDC_WD3200AAKS-75L9A0_WD-WMAV27368122 or by-path,like /dev/disk/by-path/pci-0001:00:03.0-scsi-0:0:0:0.

<device>/dev/sda</device>

Optional. If left out, AutoYaST tries to guess the device. See Tip: Skipping Devices on how to influence guessing.

A RAID must always have /dev/md as device.

initialize

If set to true, the partition table gets wiped out before AutoYaST starts the partition calculation.

<initialize config:type="boolean">true</initialize>

Optional. The default is false.

partitions

A list of <partition> entries (see Section 4.5.2, “Partition Configuration”).

<partitions config:type="list">
  <partition>...</partition>
  ...
</partitions>

Optional. If no partitions are specified, AutoYaST will create a reasonable partitioning (see Section 4.5.5, “Automated Partitioning”).

pesize

This value only makes sense with LVM.

<pesize>8M</pesize>

Optional. Default is 4M for LVM volume groups.

use

Specifies the strategy AutoYaST will use to partition the hard disk.

Choose between:

  • all (uses the whole device while calculating the new partitioning),

  • linux (only existing Linux partitions are used),

  • free (only unused space on the device is used, no other partitions are touched),

  • 1,2,3 (a list of comma separated partition numbers to use).

This parameter should be provided.

type

Specify the type of the drive,

Choose between:

  • CT_DISK for physical hard disks (default),

  • CT_LVM for LVM volume groups,

<type config:type="symbol">CT_LVM</type>

Optional. Default is CT_DISK for a normal physical hard disk.

disklabel

Describes the type of the partition table.

Choose between:

  • msdos

  • gpt

<disklabel>gpt</disklabel>

Optional. By default YaST decides what makes sense.

keep_unknown_lv

This value only makes sense for type=CT_LVM drives. If you are reusing a logical volume group and you set this to true, all existing logical volumes in that group will not be touched unless they are specified in the <partitioning> section. So you can keep existing logical volumes without specifying them.

<keep_unknown_lv config:type="boolean"
>false</keep_unknown_lv>

Optional. The default is false.

enable_snapshots

Enables snapshots for Btrfs file systems. It does not apply to other kinds of file systems.

<enable_snapshots config:type="boolean"
>false</enable_snapshots>

Optional. The default is true.

Tip
Tip: Skipping Devices

You can influence AutoYaST's device-guessing for cases where you do not specify a <device> entry on your own. Usually AutoYaST would use the first device it can find that looks reasonable but you can configure it to skip some devices like this:

<partitioning config:type="list">
  <drive>
    <initialize config:type="boolean">true</initialize>
    <skip_list config:type="list">
      <listentry>
        <!-- skip devices that use the usb-storage driver -->
        <skip_key>driver</skip_key>
        <skip_value>usb-storage</skip_value>
      </listentry>
      <listentry>
        <!-- skip devices that are smaller than 1GB -->
        <skip_key>size_k</skip_key>
        <skip_value>1048576</skip_value>
        <skip_if_less_than config:type="boolean">true</skip_if_less_than>
      </listentry>
      <listentry>
        <!-- skip devices that are larger than 100GB -->
        <skip_key>size_k</skip_key>
        <skip_value>104857600</skip_value>
        <skip_if_more_than config:type="boolean">true</skip_if_more_than>
      </listentry>
    </skip_list>
  </drive>
</partitioning>

For a list of all possible <skip_key>, run yast2 ayast_probe on an already installed system.

4.5.2 Partition Configuration

The elements listed below must be placed within the following XML structure:

<drive>
  <partitions config:type="list">
    <partition>
      ...
    </partition>
  </partitions>
</drive>

Attribute

Values

Description

create

Specify if this partition must be created or if it already exists.

<create config:type="boolean" >false</create>

If set to false, you also need to set partition_nr to tell AutoYaST the partition number.

crypt_fs

Partition will be encrypted.

<crypt_fs config:type="boolean">false</crypt_fs>

Default is false.

crypt_key

Encryption key

<crypt_key>xxxxxxxx</crypt_key>

Only needed if crypt_fs has been set to true.

mount

The mount point of this partition.

<mount>/</mount>
<mount>swap</mount>

You should have at least a root partition (/) and a swap partition.

fstopt

Mount options for this partition.

<fstopt>
  ro,noatime,user,data=ordered,acl,user_xattr
</fstopt>

See man mount for available mount options.

label

The label of the partition (useful for the mountby parameter; see below).

<label>mydata</label>

See man e2label for an example.

uuid

The uuid of the partition (only useful for the mountby parameter; see below).

<uuid
>1b4e28ba-2fa1-11d2-883f-b9a761bde3fb</uuid>

See man uuidgen.

size

The size of the partition, for example 4G, 4500M, etc. The /boot partition and the swap partition can have auto as size. Then AutoYaST calculates a reasonable size. One partition can have the value max to use all remaining space.

You can also specify the size in percentage. So 10% will use 10% of the size of the hard disk or volume group. You can mix auto, max, size, and percentage as you like.

<size>10G</size>

format

Specify if AutoYaST should format the partition.

<format config:type="boolean">false</format>

If you set create to true, then you likely want this option set to true as well.

file system

Specify the file system to use on this partition:

  • btrfs

  • ext2

  • ext3

  • ext4

  • fat

  • xfs

  • swap

<filesystem config:type="symbol"
>ext3</filesystem>

Optional. The default is btrfs for the root partition (/) and xfs for data partitions.

mkfs_options

Specify an option string that is added to the mkfs command.

<mkfs_options>-I 128</mkfs_options>

Optional. Only use this when you know what you are doing.

partition_nr

The partition number of this partition. If you have set create=false or if you use LVM, then you can specify the partition via partition_nr. You can force AutoYaST to only create primary partitions by assigning numbers below 5.

<partition_nr config:type="integer"
>2</partition_nr>

Usually, numbers 1 to 4 are primary partitions while 5 and higher are logical partitions.

partition_id

The partition_id sets the id of the partition. If you want different identifiers than 131 for Linux partition or 130 for swap, configure them with partition_id.

<partition_id config:type="integer"
>131</partition_id>

The default is 131 for Linux partition and 130 for swap.

mountby

Instead of a partition number, you can tell AutoYaST to mount a partition by device, label, uuid, path or id, which are the udev path and udev id (see /dev/disk/...).

<mountby config:type="symbol"
>label</mountby>

See label and uuid documentation above. The default depends on YaST and usually is id.

subvolumes

List of subvolumes to create for a file system of type Btrfs. This key only makes sense for file systems of type Btrfs. See Section 4.5.3, “Btrfs subvolumes” for more information.

<subvolumes config:type="list">
  <path>tmp</path>
  <path>opt</path>
  <path>srv</path>
  <path>var/crash</path>
  <path>var/lock</path>
  <path>var/run</path>
  <path>var/tmp</path>
  <path>var/spool</path>
  ...
</subvolumes>

lv_name

If this partition is on a logical volume in a volume group, specify the logical volume name here (see the is_lvm_vg parameter in the drive configuration).

<lv_name>opt_lv</lv_name>

stripes

An integer that configures LVM striping. Specify across how many devices you want to stripe (spread data).

<stripes config:type="integer">2</stripes>

stripesize

Specify the size of each block in KB.

<stripesize config:type="integer"
>4</stripesize>

lvm_group

If this is a physical partition used by (part of) a volume group (LVM), you need to specify the name of the volume group here.

<lvm_group>system</lvm_group>

pool

pool must be set to true if the LVM logical volume should be an LVM thin pool.

<pool config:type="boolean">false</pool>

used_pool

The name of the LVM thin pool that is used as a data store for this thin logical volume. If this is set to something non-empty, it implies that the volume is a so-called thin logical volume.

<used_pool>my_thin_pool</used_pool>

raid_name

If this physical volume is part of a RAID, specify the name of the RAID.

<raid_name>/dev/md0</raid_name>

raid_type

Specify the type of the RAID.

<raid_type>raid1</raid_type>

raid_options

Specify RAID options, see below.

<raid_options>...</raid_options>

resize

This boolean must be true if an existing partition should be resized. In this case, you want to set create to false and usually you do not want to format the partition. You need to tell AutoYaST the partition_nr and the size. The size can be in percentage of the original size or a number, like 800M. max and auto do not work as size here.

<resize config:type="boolean"
>false</resize>

Resizing only works with physical disks, not with LVM volumes.

4.5.3 Btrfs subvolumes

As mentioned in Section 4.5.2, “Partition Configuration”, it is possible to define a set of subvolumes for each Btrfs file system. In its simplest form, is just a list of entries:

<subvolumes config:type="list">
  <path>tmp</path>
  <path>opt</path>
  <path>srv</path>
  <path>var/crash</path>
  <path>var/lock</path>
  <path>var/run</path>
  <path>var/tmp</path>
  <path>var/spool</path>
</subvolumes>

AutoYaST supports disabling copy-on-write for a given subvolume. In that case, a slightly more complex syntax should be used:

<subvolumes config:type="list">
<listentry>tmp</listentry>
<listentry>opt</listentry>
<listentry>srv</listentry>
<listentry>
  <path>var/lib/pgsql</path>
  <copy_on_write config:type="boolean">false<copy_on_write>
</listentry>
</subvolumes>

If there is a default subvolume used for the distribution (for example @ in SUSE Linux Enterprise Server), the name of this default subvolume is automatically prefixed to the names in this list. This behavior can be disabled by setting the btrfs_set_default_subvolume_name in the general/storage section.

<general>
  <storage>
    <btrfs_set_default_subvolume_name config:type="boolean">false</btrfs_set_default_subvolume_name>
  </storage>
</general>

4.5.4 RAID Options

The following elements must be placed within the following XML structure:

<partition>
  <raid_options>
    ...
  </raid_options>
</partition>

Attribute

Values

Description

chunk_size

<chunk_size>4</chunk_size>

parity_algorithm

Possible values are:

left_asymmetric, left_symmetric, right_asymmetric, right_symmetric.

For RAID6 and RAID10 the following values can be used:

parity_first, parity_last, left_asymmetric_6, left_symmetric_6, right_asymmetric_6, right_symmetric_6, parity_first_6, n2, o2, f2, n3, o3, f3 for RAID6 and RAID10.

<parity_algorithm
>left_asymmetric</parity_algorithm>

raid_type

Possible values are: raid0, raid1, raid5, raid6 and raid10.

<raid_type>raid1</raid_type>

The default is raid1.

device_order

This list contains the optional order of the physical devices:

<device_order config:type="list">
   <device>/dev/sdb2</device>
   <device>/dev/sda1</device>
   ...
</device_order>

This is optional and the default is alphabetical order.

4.5.5 Automated Partitioning

For automated partitioning, you only need to provide the sizes and mount points of partitions. All other data needed for successful partitioning is calculated during installation—unless provided in the control file.

If no partitions are defined and the specified drive is also the drive where the root partition should be created, the following partitions are created automatically:

  • /boot

    The size of the /boot partition is determined by the architecture of the target system.

  • swap

    The size of the swap partition is determined by the amount of memory available in the system.

  • / (root partition)

    The size of the root partition is determined by the space left after creating swap and /boot.

Depending on the initial status of the drive and how it was previously partitioned, it is possible to create the default partitioning in the following ways:

Use Free Space

If the drive is already partitioned, it is possible to create the new partitions using the free space on the hard disk. This requires the availability of sufficient space for all selected packages in addition to swap.

Reuse all available space

Use this option to delete all existing partitions (Linux and non-Linux).

Reuse all available Linux partitions

This option deletes all existing Linux partitions. Other partitions (for example Windows partitions) remain untouched. Note that this works only if the Linux partitions are at the end of the device.

Reuse only specified partitions

This option allows you to select specific partitions to delete. Start the selection with the last available partition.

Repartitioning only works if the selected partitions are neighbors and located at the end of the device.

Important
Important: Beware of Data Loss

The value provided in the use property determines how existing data and partitions are treated. The value all means that the entire disk will be erased. Make backups and use the confirm property if you need to keep some partitions with important data. Otherwise, no pop-ups will notify you about partitions being deleted.

If multiple drives are in the target system, identify all drives with their device names and specify how the partitioning should be performed.

Partition sizes can be given in gigabytes, megabytes or can be set to a flexible value using the keywords auto and max. max uses all available space on a drive, therefore should only be set for the last partition on the drive. With auto the size of a swap or boot partition is determined automatically, depending on the memory available and the type of the system.

A fixed size can be given as shown below:

1GB, 1G, 1000MB, or 1000M will all create a partition of the size 1 Gigabyte.

Example 4.3: Automated Partitioning

The following is an example of a single drive system, which is not pre-partitioned and should be automatically partitioned according to the described pre-defined partition plan. If you do not specify the device, it will be automatically detected.

<partitioning  config:type="list">
  <drive>
    <device>/dev/sda</device>
    <use>all</use>
  </drive>
</partitioning>

A more detailed example shows how existing partitions and multiple drives are handled.

Example 4.4: Detailed Automated Partitioning
<partitioning  config:type="list">
  <drive>
    <device>/dev/sda</device>
    <partitions config:type="list">
      <partition>
        <mount>/</mount>
        <size>10G</size>
      </partition>
      <partition>
        <mount>swap</mount>
        <size>1G</size>
      </partition>
    </partitions>
  </drive>
  <drive>
    <device>/dev/sdb</device>
    <use>all</use>
    <partitions config:type="list">
      <partition>
        <filesystem  config:type="symbol">reiser</filesystem>
        <mount>/data1</mount>
        <size>15G</size>
      </partition>
      <partition>
        <filesystem  config:type="symbol">jfs</filesystem>
        <mount>/data2</mount>
        <size>auto</size>
      </partition>
    </partitions>
    <use>free</use>
  </drive>
</partitioning>

4.5.6 Advanced Partitioning Features

4.5.6.1 Wipe out Partition Table

Usually this is not needed because AutoYaST can delete partitions one by one automatically. But you need the option to let AutoYaST clear the partition table instead of deleting partitions individually.

Go to the drive section and add:

<initialize config:type="boolean">true</initialize>

With this setting AutoYaST will delete the partition table before it starts to analyze the actual partitioning and calculates its partition plan. Of course this means, that you cannot keep any of your existing partitions.

4.5.6.2 Mount Options

By default a file system to be mounted is identified in /etc/fstab by the device name. This identification can be changed so the file system is found by searching for a UUID or a volume label. Note that not all file systems can be mounted by UUID or a volume label. To specify how a partition is to be mounted, use the mountby property which has the symbol type. Possible options are:

  • device (default)

  • label

  • UUID

If you choose to mount the partition using a label, the name entered for the label property is used as the volume label.

Add any valid mount option in the fourth field of /etc/fstab. Multiple options are separated by commas. Possible fstab options:

Mount read-only (ro)

No write access to the file system. Default is false.

No access time (noatime)

Access times are not updated when a file is read. Default is false.

Mountable by User (user)

The file system can be mounted by a normal user. Default is false.

Data Journaling Mode (ordered, journal, writeback)
journal

All data is committed to the journal prior to being written to the main file system.

ordered

All data is directly written to the main file system before its metadata is committed to the journal.

writeback

Data ordering is not preserved.

Access Control List (acl)

Enable access control lists on the file system.

Extended User Attributes (user_xattr)

Allow extended user attributes on the file system.

Example 4.5: Mount Options
<partitions config:type="list">
  <partition>
    <filesystem config:type="symbol">reiser</filesystem>
    <format config:type="boolean">true</format>
    <fstopt>ro,noatime,user,data=ordered,acl,user_xattr</fstopt>
    <mount>/local</mount>
    <mountby config:type="symbol">uuid</mountby>
    <partition_id config:type="integer">131</partition_id>
    <size>10G</size>
  </partition>
</partitions>

4.5.6.3 Keeping Specific Partitions

In some cases you should leave partitions untouched and only format specific target partitions, rather than creating them from scratch. For example, if different Linux installations coexist, or you have another operating system installed, likely you do not want to wipe these out. You may also want to leave data partitions untouched.

Such scenarios require certain knowledge about the target systems and hard disks. Depending on the scenario, you might need to know the exact partition table of the target hard disk with partition ids, sizes and numbers. With this data you can tell AutoYaST to keep certain partitions, format others and create new partitions if needed.

The following example will keep partitions 1, 2 and 5 and delete partition 6 to create two new partitions. All remaining partitions will only be formatted.

Example 4.6: Keeping partitions
<partitioning config:type="list">
  <drive>
    <device>/dev/sdc</device>
      <partitions config:type="list">
        <partition>
          <create config:type="boolean">false</create>
          <format config:type="boolean">true</format>
          <mount>/</mount>
          <partition_nr config:type="integer">1</partition_nr>
        </partition>
        <partition>
          <create config:type="boolean">false</create>
          <format config:type="boolean">false</format>
          <partition_nr config:type="integer">2</partition_nr>
          <mount>/space</mount>
        </partition>
        <partition>
          <create config:type="boolean">false</create>
          <format config:type="boolean">true</format>
          <filesystem config:type="symbol">swap</filesystem>
          <partition_nr config:type="integer">5</partition_nr>
          <mount>swap</mount>
        </partition>
        <partition>
          <format config:type="boolean">true</format>
          <mount>/space2</mount>
          <size>5G</size>
        </partition>
        <partition>
          <format config:type="boolean">true</format>
          <mount>/space3</mount>
          <size>max</size>
        </partition>
      </partitions>
    <use>6</use>
  </drive>
</partitioning>

The last example requires exact knowledge of the existing partition table and the partition numbers of those partitions that should be kept. In some cases however, such data may not be available, especially in a mixed hardware environment with different hard disk types and configurations. The following scenario is for a system with a non-Linux OS with a designated area for a Linux installation.

Keeping partitions
Figure 4.1: Keeping partitions

In this scenario, shown in figure Figure 4.1, “Keeping partitions”, AutoYaST will not create new partitions. Instead it searches for certain partition types on the system and uses them according to the partitioning plan in the control file. No partition numbers are given in this case, only the mount points and the partition types (additional configuration data can be provided, for example file system options, encryption and file system type).

Example 4.7: Auto-detection of partitions to be kept.
<partitioning config:type="list">
  <drive>
    <partitions config:type="list">
      <partition>
        <create config:type="boolean">false</create>
        <format config:type="boolean">true</format>
        <mount>/</mount>
        <partition_id config:type="integer">131</partition_id>
      </partition>
      <partition>
        <create config:type="boolean">false</create>
        <format config:type="boolean">true</format>
        <filesystem config:type="symbol">swap</filesystem>
        <partition_id config:type="integer">130</partition_id>
        <mount>swap</mount>
      </partition>
    </partitions>
  </drive>
</partitioning>

4.5.7 Using an Existing Mount Table (fstab)

Note
Note: Cannot Be Combined with partitioning Section

This section will be ignored if you have defined your own partitioning section too.

This option will allow AutoYaST to use an existing /etc/fstab and use the partition data from a previous installation. All partitions are kept and no new partitions are created. The partitions will be formatted and mounted as specified in /etc/fstab on a Linux root partition.

Although the default behavior is to format all partitions, it is also possible to leave some partitions (for example data partitions) untouched and only mount them. If multiple installations are found on the system (multiple root partitions with different fstab files, the installation will abort, unless the root partition is configured in the control file. The following example illustrates how this option can be used:

Example 4.8: Reading an Existing /etc/fstab
<partitioning_advanced>
  <fstab>
    <!-- Read data from existing fstab. If multiple root partitions are
            found, use the one specified below. Otherwise the first root
            partition is taken -->
    <!-- <root_partition>/dev/sda5</root_partition> -->
    <use_existing_fstab config:type="boolean">true</use_existing_fstab>
    <!-- all partitions found in fstab will be formatted and mounted
            by default unless a partition is listed below with different
            settings -->
    <partitions config:type="list">
      <partition>
        <format config:type="boolean">false</format>
        <mount>/bootmirror</mount>
      </partition>
    </partitions>
  </fstab>
</partitioning_advanced>

4.5.8 Logical Volume Manager (LVM)

To configure LVM, first create a physical volume using the normal partitioning method described above.

Example 4.9: Create LVM Physical Volume

The following example shows how to prepare for LVM in the partitioning resource. A non-formatted partition is created on device /dev/sda1 of the type LVM and with the volume group system. This partition will use all space available on the drive.

<partitioning config:type="list">
  <drive>
    <device>/dev/sda</device>
    <partitions config:type="list">
      <partition>
        <create config:type="boolean">true</create>
        <lvm_group>system</lvm_group>
        <partition_type>primary</partition_type>
        <partition_id config:type="integer">142</partition_id>
        <partition_nr config:type="integer">1</partition_nr>
        <size>max</size>
      </partition>
    </partitions>
    <use>all</use>
  </drive>
</partitioning>
Example 4.10: LVM Logical Volumes
<partitioning config:type="list">
  <drive>
    <device>/dev/sda</device>
    <partitions config:type="list">
      <partition>
        <lvm_group>system</lvm_group>
        <partition_type>primary</partition_type>
        <size>max</size>
      </partition>
    </partitions>
    <use>all</use>
  </drive>
  <drive>
    <device>/dev/system</device>
      <is_lvm_vg config:type="boolean">true</is_lvm_vg>
      <partitions config:type="list">
        <partition>
          <filesystem config:type="symbol">reiser</filesystem>
          <lv_name>user_lv</lv_name>
          <mount>/usr</mount>
          <size>15G</size>
        </partition>
        <partition>
          <filesystem config:type="symbol">reiser</filesystem>
          <lv_name>opt_lv</lv_name>
          <mount>/opt</mount>
          <size>10G</size>
        </partition>
        <partition>
          <filesystem config:type="symbol">reiser</filesystem>
          <lv_name>var_lv</lv_name>
          <mount>/var</mount>
          <size>1G</size>
        </partition>
      </partitions>
      <pesize>4M</pesize>
    <use>all</use>
  </drive>
</partitioning>

It is possible to set the size to max for the logical volumes. Of course, you can only use max for one(!) logical volume. You cannot set two logical volumes in one volume group to max.

4.5.9 Software RAID

Using AutoYaST, you can create and assemble software RAID devices. The supported RAID levels are the following:

RAID 0

This level increases your disk performance. There is no redundancy in this mode. If one of the drives crashes, data recovery will not be possible.

RAID 1

This mode offers the best redundancy. It can be used with two or more disks. An exact copy of all data is maintained on all disks. As long as at least one disk is still working, no data is lost. The partitions used for this type of RAID should have approximately the same size.

RAID 5

This mode combines management of a larger number of disks and still maintains some redundancy. This mode can be used on three disks or more. If one disk fails, all data is still intact. If two disks fail simultaneously, all data is lost.

Multipath

This mode allows access to the same physical device via multiple controllers for redundancy against a fault in a controller card. This mode can be used with at least two devices.

As with LVM, you need to create all RAID partitions first and assign them to the RAID device you want to create afterward. Additionally you need to specify whether a partition or a device should be part of the RAID or if it should be a Spare device.

The following example shows a simple RAID1 configuration:

Example 4.11: RAID1 configuration
<partitioning config:type="list">
  <drive>
    <device>/dev/sda</device>
    <partitions config:type="list">
      <partition>
        <partition_id config:type="integer">253</partition_id>
        <format config:type="boolean">false</format>
        <raid_name>/dev/md0</raid_name>
        <raid_type>raid</raid_type>
        <size>4G</size>
      </partition>

        <!-- Insert a configuration for the regular partitions located on
                /dev/sda here (for example / and swap) -->

    </partitions>
    <use>all</use>
  </drive>
  <drive>
    <device>/dev/sdb</device>
    <partitions config:type="list">
      <partition>
        <format config:type="boolean">false</format>
        <partition_id config:type="integer">253</partition_id>
        <raid_name>/dev/md0</raid_name>
        <raid_type>raid</raid_type>
        <size>4gb</size>
      </partition>
    </partitions>
    <use>all</use>
  </drive>
  <drive>
    <device>/dev/md</device>
    <partitions config:type="list">
      <partition>
        <filesystem config:type="symbol">reiser</filesystem>
        <format config:type="boolean">true</format>
        <mount>/space</mount>
        <partition_id config:type="integer">131</partition_id>
        <partition_nr config:type="integer">0</partition_nr>
        <raid_options>
          <chunk_size>4</chunk_size>
          <parity_algorithm>left-asymmetric</parity_algorithm>
          <raid_type>raid1</raid_type>
        </raid_options>
      </partition>
    </partitions>
    <use>all</use>
  </drive>
</partitioning>

Keep the following in mind when configuring a RAID:

  • The device for raid is always /dev/md

  • The property partition_nr is used to determine the MD device number. If partition_nr is equal to 0, then /dev/md0 is configured.

  • All RAID-specific options are contained in the raid_options resource.

4.5.10 IBM z Systems Specific Configuration

4.5.10.1 Configuring DASD Disks

The elements listed below must be placed within the following XML structure:

<dasd>
 <devices config:type="list">
  <listentry>
   ...
  </listentry>
 </devices>
</dasd>

tags in the <profile> section. Each disk needs to be configured in a separate <listentry> ... </listentry> section.

Attribute

Values

Description

device

DASD is the only value allowed

<device
>DASD</dev_name>

dev_name

The device (dasdN) you want to configure in this section.

<dev_name
>/dev/dasda</dev_name>

Optional but recommended. If left out, AutoYaST tries to guess the device.

channel

Channel by which the disk is accessed.

<channel>0.0.0150</channel>

Mandatory.

diag

Enable or disable the use of DIAG. Possible values are true (enable) or false (disable).

<diag
config:type="boolean">true</diag>

Optional.

4.5.10.2 Configuring zFCP Disks

The following elements must be placed within the following XML structure:

<profile>
  <zfcp>
    <devices config:type="list">
      <listentry>
        ...
      </listentry>
    </devices>
  </zfcp>
<profile>

Each disk needs to be configured in a separate listentry section.

Attribute

Values

controller_id

Channel number

<controller_id
>0.0.fc00</controller_id>

4.6 iSCSI Initiator Overview

Using the iscsi-client resource, you can configure the target machine as an iSCSI client.

Example 4.12: iSCSI client
  <iscsi-client>
    <initiatorname>iqn.2013-02.de.suse:01:e229358d2dea</initiatorname>
    <targets config:type="list">
      <listentry>
         <authmethod>None</authmethod>
         <portal>192.168.1.1:3260</portal>
         <startup>onboot</startup>
         <target>iqn.2001-05.com.doe:test</target>
         <iface>default</iface>
      </listentry>
    </targets>
    <version>1.0</version>
  </iscsi-client>

Attribute

Description

initiatorname

InitiatorName is a value from /etc/iscsi/initiatorname.iscsi. In case you have iBFT, this value will be added from there and you are only able to change it in the BIOS setup.

version

Version of the YaST module. Default: 1.0

targets

List of targets. Each entry contains:

authmethod Authentication method: None/CHAP

portal Portal address

startup Value: manual/onboot

target Target name

iface Interface name

4.7 Fibre Channel over Ethernet Configuration (FCoE)

Using the fcoe_cfg resource, you can configure a Fibre Channel over Ethernet (FCoE).

Example 4.13: FCoE configuration
  <fcoe-client>
    <fcoe_cfg>
      <DEBUG>no</DEBUG>
      <USE_SYSLOG>yes</USE_SYSLOG>
    </fcoe_cfg>
    <interfaces config:type="list">
      <listentry>
        <dev_name>eth3</dev_name>
        <mac_addr>01:000:000:000:42:42</mac_addr>
        <device>Gigabit 1313</device>
        <vlan_interface>200</vlan_interface>
        <fcoe_vlan>eth3.200</fcoe_vlan>
        <fcoe_enable>yes</fcoe_enable>
        <dcb_required>yes</dcb_required>
        <auto_vlan>no</auto_vlan>
        <dcb_capable>no</dcb_capable>
        <cfg_device>eth3.200</cfg_device>
      </listentry>
    </interfaces>
    <service_start>
      <fcoe config:type="boolean">true</fcoe>
      <lldpad config:type="boolean">true</lldpad>
    </service_start>
  </fcoe-client>

Attribute

Description

Values

fcoe_cfg

DEBUG is used to enable or disable debugging messages from the fcoe service script and fcoemon.

USE_SYSLOG messages are sent to the system log if set to yes (data are logged to /var/log/messages).

yes/no

interfaces

List of network cards including the status of VLAN and FCoE configuration.

service_start

Enable or disable the start of the services fcoe and lldpad at boot time.

Starting the service fcoe means starting the Fibre Channel over Ethernet service daemon fcoemon which controls the FCoE interfaces and establishes a connection with the daemon lldpad.

The lldpad service provides the Link Layer Discovery Protocol agent daemon lldpad that informs fcoemon about DCB (Data Center Bridging) features and configuration of the interfaces.

yes/no

4.8 Country Settings

Language, timezone, and keyboard settings.

Example 4.14: Language
       <language>
         <language>en_GB</language>
         <languages>de_DE,en_US</languages>
       </language>

Attribute

Description

Values

language

Primary language

A list of available languages can be found under /usr/share/YaST2/data/languages

languages

Secondary languages separated by commas

A list of available languages can be found under /usr/share/YaST2/data/languages

If the configured value for the primary language is unknown, it will be reset to the default, en_US.

Example 4.15: Timezone
       <timezone>
         <hwclock>UTC</hwclock>
         <timezone>Europe/Berlin</timezone>
       </timezone>

Attribute

Description

Values

hwclock

Whether the hardware clock uses local time or UTC

localtime/UTC

timezone

Timezone

A list of available timezones can be found under /usr/share/YaST2/data/timezone_raw.ycp

Example 4.16: Keyboard
       <keyboard>
         <keymap>german</keymap>
       </keyboard>

Attribute

Description

Values

keymap

Keyboard layout

A list of available keymaps can be found in /usr/share/YaST2/data/keyboard_raw.ycp

4.9 Software

4.9.1 Package Selection with Patterns

Patterns are configured like this:

Example 4.17: Package Selection in the Control File with Patterns
<software>
  <patterns config:type="list">
    <pattern>directory_server</pattern>
  </patterns>
  <packages  config:type="list">
    <package>apache</package>
    <package>postfix</package>
  </packages>
  <do_online_update config:type="boolean">true</do_online_update>
</software>

4.9.2 Installing Additional/Customized Packages or Products

In addition to the packages available for installation on the DVD-ROMs, you can add external packages including customized kernels. Customized kernel packages must be compatible to the SUSE packages and must install the kernel files to the same locations.

Unlike in earlier in versions, you do not need a special resource in the control file to install custom and external packages. Instead you need to re-create the package database and update it with any new packages or new package versions in the source repository.

A script is provided for this task which will query packages available in the repository and create the package database. Use the command /usr/bin/create_package_descr. It can be found in the inst-source-utils package in the openSUSE Build Service. When creating the database, all languages will be reset to English.

Example 4.18: Creating a Package Database With the Additional Package inst-source-utils.rpm

The unpacked DVD is located in /usr/local/DVDs/LATEST.

cp /tmp/inst-source-utils-2016.7.26-1.2.noarch.rpm /usr/local/DVDs/LATEST/suse/noarch
cd /usr/local/DVDs/LATEST/suse
create_package_descr -d /usr/local/CDs/LATEST/suse

In the above example, the directory /usr/local/CDs/LATEST/suse contains the architecture dependent (for example x86_64) and architecture independent packages (noarch). This might look different on other architectures.

The advantage of this method is that you can keep an up-to-date repository with fixed and updated package. Additionally this method makes the creation of custom CD-ROMs easier.

To add your own module such as the SDK (SUSE Software Development Kit), add a file add_on_products.xml to the installation source in the root directory.

The following example shows how the SDK module can be added to the base product repository. The complete SDK repository will be stored in the directory /sdk.

Example 4.19: add_on_products.xml

This file describes an SDK module included in the base product.

<?xml version="1.0"?>
<add_on_products xmlns="http://www.suse.com/1.0/yast2ns"
   xmlns:config="http://www.suse.com/1.0/configns">
   <product_items config:type="list">
      <product_item>
         <name>SUSE Linux Enterprise Software Development Kit</name>
         <url>relurl:////sdk?alias=SLE_SDK</url>
         <path>/</path>
         <-- Users are asked whether to add such a product -->
         <ask_user config:type="boolean">false</ask_user>
         <-- Defines the default state of pre-selected state in case of ask_user used. -->
         <selected config:type="boolean">true</selected>
      </product_item>
   </product_items>
</add_on_products>

While a normal installation now the SDK module will be installed automatically. This will be not done via an AutoYaST installation. An additional entry would be needed for in the AutoYaST control file add-on section.

Besides this special case all other modules, extensions and add-on products can be added from almost every other locations while an AutoYaST installation.

Example 4.20: Adding SDK product auto AutoYaST configuration file
<add-on>
  <add_on_products config:type="list">
    <listentry>
      <media_url>cd:///sdk</media_url>
      <product>sle-sdk</product>
      <alias>SLES SDK</alias>
      <product_dir>/</product_dir>
      <priority config:type="integer">20</priority>
      <ask_on_error config:type="boolean">false</ask_on_error>
      <confirm_license config:type="boolean">false</confirm_license>
      <name>SUSE Linux Enterprise Software Development Kit</name>
    </listentry>
  </add_on_products>
</add-on>

Attribute

Values

media_url

Product URL. Can have the prefix cd:///, http://, ftp://,...

product

Internal product name if the add-on is a product. The command zypper products shows these names of installed products.

alias

Repository alias name. Defined by the user.

product_dir

Additional subpath. Optional.

priority

Sets the repository libzypp priority. Priority of 1 is the highest. The higher the number the lower the priority. Default is 99.

ask_on_error

AutoYaST can ask the user to make add-on products, modules or extensions available instead of reporting a time-out error when no repository can be found at the given location. Set ask_on_error to true (the default is false).

confirm_license

The user has to confirm the license. Default is false

name

Repository name. The command zypper lr shows these names of added repositories.

To use unsigned installation sources with AutoYaST, turn off the checks with the following configuration in your AutoYaST control file.

The elements listed below must be placed within the following XML structure:

<general>
  <signature-handling>
    ...
  </signature-handling>
</general>

Default values for all options are false. If an option is set to false and a package or repository fails the respective test, it is silently ignored and will not be installed. Note that setting any of these options to true is a potential security risk. Never do it when using packages or repositories from third party sources.

Attribute

Values

accept_unsigned_file

If set to true, AutoYaST will accept unsigned files like the content file.

<accept_unsigned_file config:type="boolean"
>true</accept_unsigned_file>

accept_file_without_checksum

If set to true, AutoYaST will accept files without a checksum in the content file.

<accept_file_without_checksum config:type="boolean"
>true</accept_file_without_checksum>

accept_verification_failed

If set to true, AutoYaST will accept signed files even when the verification of the signature failed.

<accept_verification_failed config:type="boolean"
>true</accept_verification_failed>

accept_unknown_gpg_key

If set to true, AutoYaST will accept new gpg keys of the installation sources, for example the key used to sign the content file.

<accept_unknown_gpg_key config:type="boolean"
>true</accept_unknown_gpg_key>

accept_non_trusted_gpg_key

Set this option to true to accept known keys you have not yet trusted.

<accept_non_trusted_gpg_key config:type="boolean"
>true</accept_non_trusted_gpg_key>

import_gpg_key

If set to true, AutoYaST will accept and import new gpg keys on the installation source in its database.

<import_gpg_key config:type="boolean"
>true</import_gpg_key>

It is possible to configure the signature handling for each add-on product, module, or extension individually. The following elements must be between the signature-handling section of the individual add-on product, module, or extension. All settings are optional. If not configured, the global signature-handling from the general section is used.

Attribute

Values

accept_unsigned_file

If set to true, AutoYaST will accept unsigned files like the content file for this add-on product.

<accept_unsigned_file config:type="boolean"
>true</accept_unsigned_file>

accept_file_without_checksum

If set to true, AutoYaST will accept files without a checksum in the content file for this add-on.

<accept_file_without_checksum config:type="boolean"
>true</accept_file_without_checksum>

accept_verification_failed

If set to true, AutoYaST will accept signed files even when the verification of the signature fails.

<accept_verification_failed config:type="boolean"
>true</accept_verification_failed>

accept_unknown_gpg_key

If all is set to true, AutoYaST will accept new gpg keys on the installation source.

<accept_unknown_gpg_key>
  <all config:type="boolean">true</all>
</accept_unknown_gpg_key>

Otherwise you can define single keys too.

<accept_unknown_gpg_key>
  <all config:type="boolean">false</all>
  <keys config:type="list">
    <keyid>3B3011B76B9D6523</keyid>
  </keys>
</accept_unknown_gpg_key>

accept_non_trusted_gpg_key

This means, the key is known, but it is not trusted by you.

You can trust all keys by adding:

<accept_non_trusted_gpg_key>
  <all config:type="boolean">true</all>
</accept_non_trusted_gpg_key>

Or you can trust specific keys:

<accept_non_trusted_gpg_key>
  <all config:type="boolean">false</all>
  <keys config:type="list">
    <keyid>3B3011B76B9D6523</keyid>
  </keys>
</accept_non_trusted_gpg_key>

import_gpg_key

If all is set to true, AutoYaST will accept and import all new gpg keys on the installation source into its database.

<import_gpg_key>
  <all config:type="boolean">true</all>
</import_gpg_key>

This can be done for specific keys only:

<import_gpg_key>
  <all config:type="boolean">false</all>
  <keys config:type="list">
    <keyid>3B3011B76B9D6523</keyid>
  </keys>
</import_gpg_key>

4.9.3 Kernel Packages

Kernel packages are not part of any selection. The required kernel is determined during installation. If the kernel package is added to any selection or to the individual package selection, installation will mostly fail because of conflicts.

To force the installation of a specific kernel, use the kernel property. The following is an example of forcing the installation of the default kernel. This kernel will be installed even if an SMP or other kernel is required.

Example 4.21: Kernel Selection in the Control File
<software>
  <kernel>kernel-default</kernel>
  ...
</software>

4.9.4 Removing Automatically Selected Packages

Some packages are selected automatically either because of a dependency or because it is available in a selection.

Removing these packages might break the system consistency, and it is not recommended to remove basic packages unless a replacement which provides the same services is provided. The best example for this case are mail transfer agent (MTA) packages. By default, postfix will be selected and installed. To use another MTA like sendmail, then postfix can be removed from the list of selected package using a list in the software resource. However, note that sendmail is not shipped with SUSE Linux Enterprise Server. The following example shows how this can be done:

Example 4.22: Package Selection in Control File
<software>
  <packages  config:type="list">
    <package>sendmail</package>
  </packages>
  <remove-packages  config:type="list">
    <package>postfix</package>
  </remove-packages>
</software>
Note
Note: Package Removal Failure

Note that it is not possible to remove a package, that is part of a pattern (see Section 4.9.1, “Package Selection with Patterns”). When specifying such a package for removal, the installation will fail with the following error message:

The package resolver run failed. Check
      your software section in the AutoYaST profile.

4.9.5 Installing Recommended Packages/Patterns

By default all recommended packages/patterns will be installed. To have a minimal installation which includes required packages only, you can switch off this behavior with the flag install_recommended. Note that this flag only affects a fresh installation and will be ignored during an upgrade.

<software>
  <install_recommended config:type="boolean">false
  </install_recommended>
</software>

Default: If this flag has not been set in the configuration file all recommended packages and no recommended pattern will be installed.

4.9.6 Installing Packages in Stage 2

To install packages after the reboot during stage two, you can use the post-packages element for that:

<software>
  <post-packages config:type="list">
    <package>yast2-cim</package>
  </post-packages>
</software>

4.9.7 Installing Patterns in Stage 2

You can also install patterns in stage 2. Use the post-patterns element for that:

<software>
  <post-patterns config:type="list">
    <pattern>apparmor</pattern>
  </post-patterns>
</software>

4.9.8 Online Update in Stage 2

You can perform an online update at the end of the installation. Set the boolean do_online_update to true. Of course this only makes sense if you add an online update repository in the suse-register/customer-center section, for example, or in a post-script. If the online update repository was already available in stage one via the add-on section, then AutoYaST has already installed the latest packages available. If a kernel update is done via online-update, a reboot at the end of stage two is triggered.

<software>
  <do_online_update config:type="boolean">true</do_online_update>
</software>

4.10 Upgrade

AutoYaST can also be used for doing a system upgrade. Besides upgrade packages, the following sections are supported too:

  • scripts/pre-scripts Running user scripts very early, before anything else really happens.

  • add-on Defining an additional add-on product.

  • language Setting language.

  • timezone Setting timezone.

  • keyboard Setting keyboard.

  • software Installing additional software/patterns. Removing installed packages.

  • suse_register Running registration process.

To control the upgrade process the following sections can be defined:

Example 4.23: Upgrade and Backup
<upgrade>
    <stop_on_solver_conflict config:type="boolean">true</stop_on_solver_conflict>
  </upgrade>
  <backup>
    <sysconfig config:type="boolean">true</sysconfig>
    <modified config:type="boolean">true</modified>
    <remove_old config:type="boolean">true</remove_old>
  </backup>

Element

Description

Comment

stop_on_solver_conflict

Halt installation if there are package dependency issues.

modified

Create backup of modified files.

sysconfig

Create backup of /etc/sysconfig directory.

remove_old

Remove backups from previous updates.

Note
Note: Starting AutoYaST in upgrade mode

To start the AutoYaST upgrade mode while booting the system, you need to select the Installation menu item and use the following boot parameters:

autoupgrade=1 autoyast=http://..

4.11 Services and Targets

With the services-manager resource you can set the default systemd target and specify in detail which system services you want to start or deactivate.

The default-target property specifies the default systemd target into which the system boots. Valid options are graphical for a graphical login, or multi-user for a console login.

The <enable config:type="list"> and <disable config:type="list"> let you explicitly enable or disable services.

Example 4.24: Configuring Services and Targets
<services-manager>
  <default_target>multi-user</default_target>
  <services>
    <disable config:type="list">
      <service>cups</service>
    </disable>
    <enable config:type="list">
      <service>sshd</service>
    </enable>
  </services>
</services-manager>

4.12 Network Configuration

Network configuration is used to connect a single workstation to an Ethernet-based LAN or to configure a dial-up connection. More complex configurations (multiple network cards, routing, etc.) are also provided.

If the following setting is set to true, YaST will keep network settings created during the installation (via Linuxrc) and/or merge it with network settings from the AutoYaST control file (if defined). AutoYaST settings have higher priority than already present configuration files. YaST will write ifcfg-* files based on the entries in the control file without removing old ones. If there is an empty or no dns and routing section, YaST will keep already existing values. Otherwise settings from the control file will be applied.

<keep_install_network
config:type="boolean">true</keep_install_network>

During the second stage, installation of additional packages will take place before the network, as described in the profile, is configured. keep_install_network is set by default to true to ensure that a network is available in case it is needed to install those packages. If all packages are installed during the first stage and the network is not needed early during the second one, setting keep_install_network to false will avoid copying the configuration.

To configure network settings and activate networking automatically, one global resource is used to store the whole network configuration.

Example 4.25: Network configuration
<networking>
  <dns>
    <dhcp_hostname config:type="boolean">true</dhcp_hostname>
    <domain>site</domain>
    <hostname>linux-bqua</hostname>
    <nameservers config:type="list">
      <nameserver>192.168.1.116</nameserver>
      <nameserver>192.168.1.117</nameserver>
      <nameserver>192.168.1.118</nameserver>
    </nameservers>
    <resolv_conf_policy>auto</resolv_conf_policy>
    <searchlist config:type="list">
      <search>example.com</search>
      <search>example.net</search>
    </searchlist>
    <write_hostname config:type="boolean">false</write_hostname>
  </dns>
  <interfaces config:type="list">
    <interface>
      <bootproto>dhcp</bootproto>
      <device>eth0</device>
      <startmode>auto</startmode>
    </interface>
    <interface>
      <bootproto>static</bootproto>
      <broadcast>127.255.255.255</broadcast>
      <device>lo</device>
      <firewall>no</firewall>
      <ipaddr>127.0.0.1</ipaddr>
      <netmask>255.0.0.0</netmask>
      <network>127.0.0.0</network>
      <prefixlen>8</prefixlen>
      <startmode>nfsroot</startmode>
      <usercontrol>no</usercontrol>
    </interface>
  </interfaces>
  <ipv6 config:type="boolean">true</ipv6>
  <keep_install_network config:type="boolean">false</keep_install_network>
  <managed config:type="boolean">false</managed>       ###### NetworkManager?
  <net-udev config:type="list">
    <rule>
      <name>eth0</name>
      <rule>ATTR{address}</rule>
      <value>00:30:6E:08:EC:80</value>
    </rule>
  </net-udev>
  <s390-devices config:type="list">
    <listentry>
      <chanids>0.0.0800 0.0.0801 0.0.0802</chanids>
      <type>qeth</type>
    </listentry>
  </s390-devices>
  <routing>
    <ipv4_forward config:type="boolean">false</ipv4_forward>
    <ipv6_forward config:type="boolean">false</ipv6_forward>
    <routes config:type="list">
      <route>
        <destination>192.168.2.1</destination>
        <device>eth0</device>
        <extrapara>foo</extrapara>
        <gateway>-</gateway>
        <netmask>-</netmask>
      </route>
      <route>
        <destination>default</destination>
        <device>eth0</device>
        <gateway>192.168.1.1</gateway>
        <netmask>-</netmask>
      </route>
      <route>
        <destination>default</destination>
        <device>lo</device>
        <gateway>192.168.5.1</gateway>
        <netmask>-</netmask>
      </route>
    </routes>
  </routing>
</networking>
Example 4.26: Bridge Interface Configuration
<interfaces config:type="list">
  <interface>
    <device>br0</device>
    <bootproto>static</bootproto>
    <bridge>yes</bridge>
    <bridge_forwarddelay>0</bridge_forwarddelay>
    <bridge_ports>eth0 eth1</bridge_ports>
    <bridge_stp>off</bridge_stp>
    <ipaddr>192.168.122.100</ipaddr>
    <netmask>255.255.255.0</netmask>
    <network>192.168.122.0</network>
    <prefixlen>24</prefixlen>
    <startmode>auto</startmode>
  </interface>
  <interface>
    <device>eth0</device>
    <bootproto>none</bootproto>
    <startmode>hotplug</startmode>
  </interface>
  <interface>
    <device>eth1</device>
    <bootproto>none</bootproto>
    <startmode>hotplug</startmode>
  </interface>
</interfaces>
Tip
Tip: IPv6 Address Support

Using IPv6 addresses in AutoYaST is fully supported. To disable IPv6 Address Support, set <ipv6 config:type="boolean">false</ipv6>

4.12.1 Persistent Names of Network Interfaces

The following elements must be between the <net-udev>...</net-udev> tags.

Element

Description

Comment

name

Network interface name, for example eth3

required

rule

ATTR{address} for a MAC based rule, KERNELS for a bus ID based rule

required

value

for example f0:de:f1:6b:da:69 for a MAC rule, 0000:00:1c.1 or 0.0.0700 for a bus ID rule

required

4.12.2 s390 Devices

The following elements must be between the <s390-devices>...</s390-devices> tags.

Element

Description

Comment

type

qeth, ctc or iucv

chanids

channel ids separated by spaces

<chanids>0.0.0700 0.0.0701 0.0.0702</chanids>

layer2

<layer2 config:type="boolean">true</layer2>

boolean; default: false

portname

QETH port name (deprecated since SLE 12 SP2)

protocol

CTC / LCS protocol, a small number (as a string)

<protocol>1</protocol>

optional

router

IUCV router/user

4.12.3 Proxy

Configure your Internet proxy (caching) settings.

Configure proxies for HTTP, HTTPS, and FTP with http_proxy, https_proxy and ftp_proxy, respectively. Addresses or names that should be directly accessible need to be specified with no_proxy (space separated values). If you are using a proxy server with authorization, fill in proxy_user and proxy_password,

Example 4.27: Network configuration: Proxy
<proxy>
  <enabled config:type="boolean">true</enabled>
  <ftp_proxy>http://192.168.1.240:3128</ftp_proxy>
  <http_proxy>http://192.168.1.240:3128</http_proxy>
  <no_proxy>www.example.com .example.org localhost</no_proxy>
  <proxy_password>testpw</proxy_password>
  <proxy_user>testuser</proxy_user>
</proxy>

4.12.4 (X)Inetd

The control file has elements to specify which superserver should be used (netd_service), whether it should be enabled (netd_status) and how the services should be configured (netd_conf).

A service description element needs two parts: key and non-key. When writing the configuration, services are matched using the key fields; to the matching service, non-key fields are applied. If no service matches, it is created. If more services match, a warning is reported. The key fields are script, service, protocol and server.

service and protocol are matched literally. script is the base name of the configuration file: usually a file in /etc/xinetd.d, for example "echo-udp", or "inetd.conf". For compatibility with 8.2, server is matched more loosely: if it is /usr/sbin/tcpd, the real server name is taken from server_args. After that, the basename of the first whitespace-separated word is taken and these values are compared.

Example 4.28: Inetd Example
<profile>
  <inetd>
    <netd_service config:type="symbol">xinetd</netd_service>
    <netd_status config:type="integer">0</netd_status>
    <netd_conf config:type="list">
      <conf>
        <script>imap</script>
        <service>pop3</service>
        <enabled config:type="boolean">true</enabled>
      </conf>
      <conf>
        <server>in.ftpd</server>
        <server_args>-A</server_args>
        <enabled config:type="boolean">true</enabled>
      </conf>
      <conf>
        <service>daytime</service>
        <protocol>tcp</protocol>
      </conf>
      <conf>...</conf>
    </netd_conf>
  </inetd>
</profile>

4.13 NIS Client

Using the nis resource, you can configure the target machine as a NIS client. The following example shows a detailed configuration using multiple domains.

Example 4.29: Network configuration: NIS
 <nis>
  <nis_broadcast config:type="boolean">true</nis_broadcast>
  <nis_broken_server config:type="boolean">true</nis_broken_server>
  <nis_by_dhcp config:type="boolean">false</nis_by_dhcp>
  <nis_domain>test.com</nis_domain>
  <nis_local_only config:type="boolean">true</nis_local_only>
  <nis_options></nis_options>
  <nis_other_domains config:type="list">
    <nis_other_domain>
      <nis_broadcast config:type="boolean">false</nis_broadcast>
      <nis_domain>domain.com</nis_domain>
      <nis_servers config:type="list">
        <nis_server>10.10.0.1</nis_server>
      </nis_servers>
    </nis_other_domain>
  </nis_other_domains>
  <nis_servers config:type="list">
    <nis_server>192.168.1.1</nis_server>
  </nis_servers>
  <start_autofs config:type="boolean">true</start_autofs>
  <start_nis config:type="boolean">true</start_nis>
</nis>

4.14 NIS Server

You can configure the target machine as a NIS server. NIS Master Server and NIS Slave Server and a combination of both are available.

Example 4.30: NIS Server Configuration
  <nis_server>
    <domain>mydomain.de</domain>
    <maps_to_serve config:type="list">
      <nis_map>auto.master</nis_map>
      <nis_map>ethers</nis_map>
    </maps_to_serve>
    <merge_passwd config:type="boolean">false</merge_passwd>
    <mingid config:type="integer">0</mingid>
    <minuid config:type="integer">0</minuid>
    <nopush config:type="boolean">false</nopush>
    <pwd_chfn config:type="boolean">false</pwd_chfn>
    <pwd_chsh config:type="boolean">false</pwd_chsh>
    <pwd_srcdir>/etc</pwd_srcdir>
    <securenets config:type="list">
      <securenet>
        <netmask>255.0.0.0</netmask>
        <network>127.0.0.0</network>
      </securenet>
    </securenets>
    <server_type>master</server_type>
    <slaves config:type="list"/>
    <start_ypbind config:type="boolean">false</start_ypbind>
    <start_yppasswdd config:type="boolean">false</start_yppasswdd>
    <start_ypxfrd config:type="boolean">false</start_ypxfrd>
  </nis_server>

Attribute

Values

Description

domain

NIS domain name.

maps_to_serve

List of maps which are available for the server.

Values: auto.master, ethers, group, hosts, netgrp, networks, passwd, protocols, rpc, services, shadow

merge_passwd

Select if your passwd file should be merged with the shadow file (only possible if the shadow file exists).

Value: true/false

mingid

Minimum GID to include in the user maps.

minuid

Minimum UID to include in the user maps.

nopush

Do not push the changes to slave servers. (Iseful if there are none).

Value: true/false

pwd_chfn

YPPWD_CHFN - allow changing the full name

Value: true/false

pwd_chsh

YPPWD_CHSH - allow changing the login shell

Value: true/false

pwd_srcdir

YPPWD_SRCDIR - source directory for passwd data

Default: /etc

securenets

List of allowed hosts to query the NIS server

A host address will be allowed if network is equal to the bitwise AND of the host's address and the netmask.

The entry with netmask 255.0.0.0 and network 127.0.0.0 must exist to allow connections from the local host.

Entering netmask 0.0.0.0 and network 0.0.0.0 gives access to all hosts.

server_type

Select whether to configure the NIS server as a master or a slave or not to configure a NIS server.

Values: master, slave, none

slaves

List of host names to configure as NIS server slaves.

start_ypbind

This host is also a NIS client (only when client is configured locally).

Value: true/false

start_yppasswdd

Also start the password daemon.

Value: true/false

start_ypxfrd

Also start the map transfer daemon. Fast Map distribution; it will speed up the transfer of maps to the slaves.

Value: true/false

4.15 LDAP Server (Authentication Server)

Using the auth-server resource, you can configure the target machine as an LDAP server. The following example shows a detailed configuration.

Example 4.31: LDAP configuration
  <auth-server>
    <daemon>
      <listeners config:type="list">
        <listentry>ldap</listentry>
        <listentry>ldapi</listentry>
      </listeners>
      <serviceEnabled>1</serviceEnabled>
      <slp/>
    </daemon>
    <databases config:type="list">
      <listentry>
        <access config:type="list">
          <listentry>
            <access config:type="list">
              <listentry>
                <control/>
                <level>write</level>
                <type>self</type>
                <value/>
              </listentry>
              <listentry>
                <control/>
                <level>auth</level>
                <type>*</type>
                <value/>
              </listentry>
            </access>
            <target>
              <attrs>userPassword</attrs>
            </target>
          </listentry>
          <listentry>
            <access config:type="list">
              <listentry>
                <control/>
                <level>write</level>
                <type>self</type>
                <value/>
              </listentry>
              <listentry>
                <control/>
                <level>read</level>
                <type>*</type>
                <value/>
              </listentry>
            </access>
            <target>
              <attrs>shadowLastChange</attrs>
            </target>
          </listentry>
          <listentry>
            <access config:type="list">
              <listentry>
                <control/>
                <level>read</level>
                <type>self</type>
                <value/>
              </listentry>
              <listentry>
                <control/>
                <level>none</level>
                <type>*</type>
                <value/>
              </listentry>
            </access>
            <target>
              <attrs>userPKCS12</attrs>
            </target>
          </listentry>
          <listentry>
            <access config:type="list">
              <listentry>
                <control/>
                <level>read</level>
                <type>*</type>
                <value/>
              </listentry>
            </access>
            <target/>
          </listentry>
        </access>
        <checkpoint config:type="list">
          <listentry>1024</listentry>
          <listentry>5</listentry>
        </checkpoint>
        <directory>/var/lib/ldap</directory>
        <entrycache>10000</entrycache>
        <idlcache>30000</idlcache>
        <indexes>
          <cn>
            <eq>1</eq>
            <sub>1</sub>
          </cn>
          <displayName>
            <eq>1</eq>
            <sub>1</sub>
          </displayName>
          <gidNumber>
            <eq>1</eq>
          </gidNumber>
          <givenName>
            <eq>1</eq>
            <sub>1</sub>
          </givenName>
          <mail>
            <eq>1</eq>
          </mail>
          <member>
            <eq>1</eq>
          </member>
          <memberUid>
            <eq>1</eq>
          </memberUid>
          <objectclass>
            <eq>1</eq>
          </objectclass>
          <sn>
            <eq>1</eq>
            <sub>1</sub>
          </sn>
          <uid>
            <eq>1</eq>
            <sub>1</sub>
          </uid>
          <uidNumber>
            <eq>1</eq>
          </uidNumber>
        </indexes>
        <rootdn>cn=Administrator,DC=corp,DC=Fabrikam,DC=COM,CN=Karen Berge</rootdn>
        <rootpw>{SSHA}LCdgE3gNejqBogGI3ac1Xf4DOIVMSk9ZQg==</rootpw>
        <suffix>DC=corp,DC=Fabrikam,DC=COM,CN=Karen Berge</suffix>
        <type>hdb</type>
      </listentry>
    </databases>
    <globals>
      <allow config:type="list"/>
      <disallow config:type="list"/>
      <loglevel config:type="list">
        <listentry>none</listentry>
      </loglevel>
      <tlsconfig>
        <caCertDir/>
        <caCertFile/>
        <certFile/>
        <certKeyFile/>
        <crlCheck>0</crlCheck>
        <crlFile/>
        <verifyClient>0</verifyClient>
      </tlsconfig>
    </globals>
    <schema config:type="list">
      <listentry>
        <definition>dn: cn=schema,cn=config
            objectClass: olcSchemaConfig
            ......
            .....
            ....
            ...
            ..
            .
        </definition>
        <name>schema</name>
      </listentry>
      <listentry>
        <includeldif>/etc/openldap/schema/core.ldif</includeldif>
      </listentry>
      <listentry>
        <includeldif>/etc/openldap/schema/cosine.ldif</includeldif>
      </listentry>
      <listentry>
        <includeldif>/etc/openldap/schema/inetorgperson.ldif</includeldif>
      </listentry>
      <listentry>
        <includeschema>/etc/openldap/schema/rfc2307bis.schema</includeschema>
      </listentry>
      <listentry>
        <includeschema>/etc/openldap/schema/yast.schema</includeschema>
      </listentry>
    </schema>
  </auth-server>

4.16 Windows Domain Membership

Using the samba-client resource, you can configure a membership of a workgroup, NT domain, or Active Directory domain.

Example 4.32: Samba Client configuration
  <samba-client>
    <disable_dhcp_hostname config:type="boolean">true</disable_dhcp_hostname>
    <global>
      <security>domain</security>
      <usershare_allow_guests>No</usershare_allow_guests>
      <usershare_max_shares>100</usershare_max_shares>
      <workgroup>WORKGROUP</workgroup>
    </global>
    <winbind config:type="boolean">false</winbind>
  </samba-client>

Attribute

Values

Description

disable_dhcp_hostname

Do not allow DHCP to change the host name.

Value: true/false

global/security

Kind of authentication regime (domain technology or Active Directory server (ADS)).

Value: ADS/domain

global/usershare_allow_guests

Sharing guest access is allowed.

Value: No/Yes

global/usershare_max_shares

Max. number of shares from smb.conf.

0 means that shares are not enabled.

global/workgroup

Workgroup or domain name.

winbind

Using winbind.

Value: true/false

4.17 Samba Server

Configuration of a simple Samba server.

Example 4.33: Samba Server configuration
  <samba-server>
    <accounts config:type="list"/>
    <backend/>
    <config config:type="list">
      <listentry>
        <name>global</name>
        <parameters>
          <security>domain</security>
          <usershare_allow_guests>No</usershare_allow_guests>
          <usershare_max_shares>100</usershare_max_shares>
          <workgroup>WORKGROUP</workgroup>
        </parameters>
      </listentry>
    </config>
    <service>Disabled</service>
    <trustdom/>
    <version>2.11</version>
  </samba-server>

Attribute

Values

Description

accounts

List of Samba accounts.

backend

List of available back-ends

Value: true/false

config

Setting additional user defined parameters in /etc/samba/smb.conf.

The example shows parameters in the global section of /etc/samba/smb.conf.

service

Samba service starts during boot.

Value: Enabled/Disabled

trustdom/

Trusted Domains.

A map of two maps (keys: establish, revoke). Each map contains entries in the format key: domainname value: password.

version

Samba version.

Default: 2.11

4.18 Authentication Client

The following is a simple example for an LDAP user authentication. NSS and PAM will automatically be configured accordingly. Required data are the name of the search base (base DN, for example, dc=mydomain,dc=com) and the IP address of the LDAP server.

Example 4.34: Network configuration: Authentication Client
<auth-client>
  <sssd>yes</sssd>
  <nssldap>no</nssldap>
  <sssd_conf>
    <sssd>
      <config_file_version>2</config_file_version>
      <services>nss, pam, sudo</services>
      <domains>EXAMPLE</domains>
    </sssd>
    <auth_domains>
      <domain>
        <domain_name>EXAMPLE</domain_name>
        <id_provider>ldap</id_provider>
        <sudo_provider>ldap</sudo_provider>
        <ldap_uri>ldap://example.com</ldap_uri>
        <ldap_sudo_search_base>ou=sudoers,dc=example,dc=com</ldap_sudo_search_base>
      </domain>
    </auth_domains>
  </sssd_conf>
</auth-client>
Tip
Tip: Using ldaps://

To use LDAP with native SSL (rather than TLS), add the ldaps resource:

<auth-client>
  <sssd_conf>
    <auth_domains>
      <domain>
        <ldaps config:type="boolean">true</ldaps>
      </domain>
    </auth_domains>
  </sssd_conf>
</auth-client>

4.19 NFS Client and Server

Configuring a system as an NFS client or an NFS server is can be done using the configuration system. The following examples show how both NFS client and server can be configured.

From SUSE Linux Enterprise Server 12 SP3 on, the structure of NFS client configuration has changed. Some global configuration options were introduced: enable_nfs4 to switch NFS4 support on/off and idmapd_domain to define domain name for rpc.idmapd (this only makes sense when NFS4 is enabled). Attention: the old structure is not compatible with the new one and the control files with an NFS section created on older releases will not work with newer products.

Example 4.35: Network Configuration: NFS Client
<nfs>
  <enable_nfs4 config:type="boolean">true</enable_nfs4>
  <idmapd_domain>suse.cz</idmapd_domain>
  <nfs_entries config:type="list">
    <nfs_entry>
      <mount_point>/home</mount_point>
      <nfs_options>sec=krb5i,intr,rw</nfs_options>
      <server_path>saurus.suse.cz:/home</server_path>
      <vfstype>nfs4</vfstype>
    </nfs_entry>
    <nfs_entry>
      <mount_point>/work</mount_point>
      <nfs_options>defaults</nfs_options>
      <server_path>bivoj.suse.cz:/work</server_path>
      <vfstype>nfs</vfstype>
    </nfs_entry>
    <nfs_entry>
      <mount_point>/mnt</mount_point>
      <nfs_options>defaults</nfs_options>
      <server_path>fallback.suse.cz:/srv/dist</server_path>
      <vfstype>nfs</vfstype>
    </nfs_entry>
  </nfs_entries>
</nfs>
Example 4.36: Network Configuration: NFS Server
<nfs_server>
  <nfs_exports config:type="list">
    <nfs_export>
      <allowed config:type="list">
        <allowed_clients>*(ro,root_squash,sync)</allowed_clients>
      </allowed>
      <mountpoint>/home</mountpoint>
    </nfs_export>
    <nfs_export>
      <allowed config:type="list">
        <allowed_clients>*(ro,root_squash,sync)</allowed_clients>
      </allowed>
      <mountpoint>/work</mountpoint>
    </nfs_export>
  </nfs_exports>
  <start_nfsserver config:type="boolean">true</start_nfsserver>
</nfs_server>

4.20 NTP Client

Select whether to start the NTP daemon when booting the system. The NTP daemon resolves host names when initializing.

To run NTP daemon in chroot jail, set start_in_chroot. Starting any daemon in a chroot jail is more secure and strongly recommended. To adjust NTP servers, peers, local clocks, and NTP broadcasting, add the appropriate entry to the control file. An example of various configuration options is shown below.

Example 4.37: Network configuration: NTP Client
<ntp-client>
  <configure_dhcp config:type="boolean">false</configure_dhcp>
  <peers config:type="list">
    <peer>
      <address>ntp.example.com</address>
      <options></options>
      <type>server</type>
    </peer>
  </peers>
  <start_at_boot config:type="boolean">true</start_at_boot>
  <start_in_chroot config:type="boolean">true</start_in_chroot>
</ntp-client>

4.21 Mail Configuration

For the mail configuration of the client, this module lets you create a detailed mail configuration. The module contains various options. We recommended you use it at least for the initial configuration.

Example 4.38: Mail Configuration
<mail>
  <aliases config:type="list">
    <alias>
      <alias>root</alias>
      <comment></comment>
      <destinations>foo</destinations>
    </alias>
    <alias>
      <alias>test</alias>
      <comment></comment>
      <destinations>foo</destinations>
    </alias>
  </aliases>
  <connection_type config:type="symbol">permanent</connection_type>
  <fetchmail config:type="list">
    <fetchmail_entry>
      <local_user>foo</local_user>
      <password>bar</password>
      <protocol>POP3</protocol>
      <remote_user>foo</remote_user>
      <server>pop.foo.com</server>
    </fetchmail_entry>
    <fetchmail_entry>
      <local_user>test</local_user>
      <password>bar</password>
      <protocol>IMAP</protocol>
      <remote_user>test</remote_user>
      <server>blah.com</server>
    </fetchmail_entry>
  </fetchmail>
  <from_header>test.com</from_header>
  <listen_remote config:type="boolean">true</listen_remote>
  <local_domains config:type="list">
    <domains>test1.com</domains>
  </local_domains>
  <masquerade_other_domains config:type="list">
      <domain>blah.com</domain>
  </masquerade_other_domains>
  <masquerade_users config:type="list">
    <masquerade_user>
      <address>joe@test.com</address>
      <comment></comment>
      <user>joeuser</user>
    </masquerade_user>
    <masquerade_user>
      <address>bar@test.com</address>
      <comment></comment>
      <user>foo</user>
    </masquerade_user>
  </masquerade_users>
  <mta config:type="symbol">postfix</mta>
  <outgoing_mail_server>test.com</outgoing_mail_server>
  <postfix_mda config:type="symbol">local</postfix_mda>
  <smtp_auth config:type="list">
    <listentry>
      <password>bar</password>
      <server>test.com</server>
      <user>foo</user>
    </listentry>
  </smtp_auth>
  <use_amavis config:type="boolean">true</use_amavis>
  <virtual_users config:type="list">
    <virtual_user>
      <alias>test.com</alias>
      <comment></comment>
      <destinations>foo.com</destinations>
    </virtual_user>
    <virtual_user>
      <alias>geek.com</alias>
      <comment></comment>
      <destinations>bar.com</destinations>
    </virtual_user>
  </virtual_users>
</mail>

4.22 HTTP Server Configuration

This section is used for configuration of an Apache HTTP server.

For less experienced users, we would suggest to configure the Apache server using the HTTP server YaST module. After that, call the AutoYaST configuration module, select the HTTP server YaST module and clone the Apache settings. These settings can be exported via the menu File.

Example 4.39: HTTP Server Configuration
  <http-server>
    <Listen config:type="list">
      <listentry>
        <ADDRESS/>
        <PORT>80</PORT>
      </listentry>
    </Listen>
    <hosts config:type="list">
      <hosts_entry>
        <KEY>main</KEY>
        <VALUE config:type="list">
          <listentry>
            <KEY>DocumentRoot</KEY>
            <OVERHEAD>
            #
            # Global configuration that will be applicable for all
            # virtual hosts, unless deleted here or overriden elsewhere.
            #
            </OVERHEAD>
            <VALUE>"/srv/www/htdocs"</VALUE>
          </listentry>
          <listentry>
            <KEY>_SECTION</KEY>
            <OVERHEAD>
            #
            # Configure the DocumentRoot
            #
            </OVERHEAD>
            <SECTIONNAME>Directory</SECTIONNAME>
            <SECTIONPARAM>"/srv/www/htdocs"</SECTIONPARAM>
            <VALUE config:type="list">
              <listentry>
                <KEY>Options</KEY>
                <OVERHEAD>
                # Possible values for the Options directive are "None", "All",
                # or any combination of:
                #   Indexes Includes FollowSymLinks SymLinksifOwnerMatch
                #   ExecCGI MultiViews
                #
                # Note that "MultiViews" must be named *explicitly*
                # --- "Options All"
                # does not give it to you.
                #
                # The Options directive is both complicated and important.
                #  Please see
                #  http://httpd.apache.org/docs/2.4/mod/core.html#options
                # for more information.
                </OVERHEAD>
                <VALUE>None</VALUE>
              </listentry>
              <listentry>
                <KEY>AllowOverride</KEY>
                <OVERHEAD>
                # AllowOverride controls what directives may be placed in
                # .htaccess files. It can be "All", "None", or any combination
                # of the keywords:
                #   Options FileInfo AuthConfig Limit
                </OVERHEAD>
                <VALUE>None</VALUE>
              </listentry>
              <listentry>
                <KEY>_SECTION</KEY>
                <OVERHEAD>
                # Controls who can get stuff from this server.
                </OVERHEAD>
                <SECTIONNAME>IfModule</SECTIONNAME>
                <SECTIONPARAM>!mod_access_compat.c</SECTIONPARAM>
                <VALUE config:type="list">
                  <listentry>
                    <KEY>Require</KEY>
                    <VALUE>all granted</VALUE>
                  </listentry>
                </VALUE>
              </listentry>
              <listentry>
                <KEY>_SECTION</KEY>
                <SECTIONNAME>IfModule</SECTIONNAME>
                <SECTIONPARAM>mod_access_compat.c</SECTIONPARAM>
                <VALUE config:type="list">
                  <listentry>
                    <KEY>Order</KEY>
                    <VALUE>allow,deny</VALUE>
                  </listentry>
                  <listentry>
                    <KEY>Allow</KEY>
                    <VALUE>from all</VALUE>
                  </listentry>
                </VALUE>
              </listentry>
            </VALUE>
          </listentry>
          <listentry>
            <KEY>Alias</KEY>
            <OVERHEAD>
            # Aliases: aliases can be added as needed (with no limit).
            # The format is Alias fakename realname
            #
            # Note that if you include a trailing / on fakename then the
            # server will require it to be present in the URL.  So "/icons"
            # is not aliased in this example, only "/icons/".  If the fakename
            # is slash-terminated, then the realname must also be slash
            # terminated, and if the fakename omits the trailing slash, the
            # realname must also omit it.
            # We include the /icons/ alias for FancyIndexed directory listings.
            # If you do not use FancyIndexing, you may comment this out.
            #
            </OVERHEAD>
            <VALUE>/icons/ "/usr/share/apache2/icons/"</VALUE>
          </listentry>
          <listentry>
            <KEY>_SECTION</KEY>
            <OVERHEAD>
            </OVERHEAD>
            <SECTIONNAME>Directory</SECTIONNAME>
            <SECTIONPARAM>"/usr/share/apache2/icons"</SECTIONPARAM>
            <VALUE config:type="list">
              <listentry>
                <KEY>Options</KEY>
                <VALUE>Indexes MultiViews</VALUE>
              </listentry>
              <listentry>
                <KEY>AllowOverride</KEY>
                <VALUE>None</VALUE>
              </listentry>
              <listentry>
                <KEY>_SECTION</KEY>
                <SECTIONNAME>IfModule</SECTIONNAME>
                <SECTIONPARAM>!mod_access_compat.c</SECTIONPARAM>
                <VALUE config:type="list">
                  <listentry>
                    <KEY>Require</KEY>
                    <VALUE>all granted</VALUE>
                  </listentry>
                </VALUE>
              </listentry>
              <listentry>
                <KEY>_SECTION</KEY>
                <SECTIONNAME>IfModule</SECTIONNAME>
                <SECTIONPARAM>mod_access_compat.c</SECTIONPARAM>
                <VALUE config:type="list">
                  <listentry>
                    <KEY>Order</KEY>
                    <VALUE>allow,deny</VALUE>
                  </listentry>
                  <listentry>
                    <KEY>Allow</KEY>
                    <VALUE>from all</VALUE>
                  </listentry>
                </VALUE>
              </listentry>
            </VALUE>
          </listentry>
          <listentry>
            <KEY>ScriptAlias</KEY>
            <OVERHEAD>
            # ScriptAlias: This controls which directories contain server
            # scripts. ScriptAliases are essentially the same as Aliases,
            # except that documents in the realname directory are treated
            # as applications and run by the server when requested rather
            # than as documents sent to the client.
            # The same rules about trailing "/" apply to ScriptAlias
            # directives as to Alias.
            #
            </OVERHEAD>
            <VALUE>/cgi-bin/ "/srv/www/cgi-bin/"</VALUE>
          </listentry>
          <listentry>
            <KEY>_SECTION</KEY>
            <OVERHEAD>
            # "/srv/www/cgi-bin" should be changed to wherever your
            # ScriptAliased CGI directory exists, if you have that configured.
            #
            </OVERHEAD>
            <SECTIONNAME>Directory</SECTIONNAME>
            <SECTIONPARAM>"/srv/www/cgi-bin"</SECTIONPARAM>
            <VALUE config:type="list">
              <listentry>
                <KEY>AllowOverride</KEY>
                <VALUE>None</VALUE>
              </listentry>
              <listentry>
                <KEY>Options</KEY>
                <VALUE>+ExecCGI -Includes</VALUE>
              </listentry>
              <listentry>
                <KEY>_SECTION</KEY>
                <SECTIONNAME>IfModule</SECTIONNAME>
                <SECTIONPARAM>!mod_access_compat.c</SECTIONPARAM>
                <VALUE config:type="list">
                  <listentry>
                    <KEY>Require</KEY>
                    <VALUE>all granted</VALUE>
                  </listentry>
                </VALUE>
              </listentry>
              <listentry>
                <KEY>_SECTION</KEY>
                <SECTIONNAME>IfModule</SECTIONNAME>
                <SECTIONPARAM>mod_access_compat.c</SECTIONPARAM>
                <VALUE config:type="list">
                  <listentry>
                    <KEY>Order</KEY>
                    <VALUE>allow,deny</VALUE>
                  </listentry>
                  <listentry>
                    <KEY>Allow</KEY>
                    <VALUE>from all</VALUE>
                  </listentry>
                </VALUE>
              </listentry>
            </VALUE>
          </listentry>
          <listentry>
            <KEY>_SECTION</KEY>
            <OVERHEAD>
            # UserDir: The name of the directory that is appended onto a
            # user's home directory if a ~user request is received.
            # To disable it, simply remove userdir from the list of modules
            # in APACHE_MODULES in /etc/sysconfig/apache2.
            #
            </OVERHEAD>
            <SECTIONNAME>IfModule</SECTIONNAME>
            <SECTIONPARAM>mod_userdir.c</SECTIONPARAM>
            <VALUE config:type="list">
              <listentry>
                <KEY>UserDir</KEY>
                <OVERHEAD>
                # Note that the name of the user directory ("public_html")
                # cannot simply be changed here, since it is a compile time
                # setting. The apache package would have to be rebuilt.
                # You could work around by deleting /usr/sbin/suexec, but
                # then all scripts from the directories would be executed
                # with the UID of the webserver.
                </OVERHEAD>
                <VALUE>public_html</VALUE>
              </listentry>
              <listentry>
                <KEY>Include</KEY>
                <OVERHEAD>
                # The actual configuration of the directory is in
                # /etc/apache2/mod_userdir.conf.
                </OVERHEAD>
                <VALUE>/etc/apache2/mod_userdir.conf</VALUE>
              </listentry>
            </VALUE>
          </listentry>
          <listentry>
            <KEY>IncludeOptional</KEY>
            <OVERHEAD>
            # Include all *.conf files from /etc/apache2/conf.d/.
            #
            # This is mostly meant as a place for other RPM packages to drop
            # in their configuration snippet.
            #
            # 
            # You can comment this out here if you want those bits include
            # only in a certain virtual host, but not here.
            </OVERHEAD>
            <VALUE>/etc/apache2/conf.d/*.conf</VALUE>
          </listentry>
          <listentry>
            <KEY>IncludeOptional</KEY>
            <OVERHEAD>
            # The manual... if it is installed ('?' means it will not complain)
            </OVERHEAD>
            <VALUE>/etc/apache2/conf.d/apache2-manual?conf</VALUE>
          </listentry>
          <listentry>
            <KEY>ServerName</KEY>
            <VALUE>linux-wtyj</VALUE>
          </listentry>
          <listentry>
            <KEY>ServerAdmin</KEY>
            <OVERHEAD>
            </OVERHEAD>
            <VALUE>root@linux-wtyj</VALUE>
          </listentry>
          <listentry>
            <KEY>NameVirtualHost</KEY>
            <VALUE>192.168.43.2</VALUE>
          </listentry>
        </VALUE>
      </hosts_entry>
      <hosts_entry>
        <KEY>192.168.43.2/secondserver.suse.de</KEY>
        <VALUE config:type="list">
          <listentry>
            <KEY>DocumentRoot</KEY>
            <VALUE>/srv/www/htdocs</VALUE>
          </listentry>
          <listentry>
            <KEY>ServerName</KEY>
            <VALUE>secondserver.suse.de</VALUE>
          </listentry>
          <listentry>
            <KEY>ServerAdmin</KEY>
            <VALUE>second_server@suse.de</VALUE>
          </listentry>
          <listentry>
            <KEY>_SECTION</KEY>
            <SECTIONNAME>Directory</SECTIONNAME>
            <SECTIONPARAM>/srv/www/htdocs</SECTIONPARAM>
            <VALUE config:type="list">
              <listentry>
                <KEY>AllowOverride</KEY>
                <VALUE>None</VALUE>
              </listentry>
              <listentry>
                <KEY>Require</KEY>
                <VALUE>all granted</VALUE>
              </listentry>
            </VALUE>
          </listentry>
        </VALUE>
      </hosts_entry>
    </hosts>
    <modules config:type="list">
      <module_entry>
        <change>enable</change>
        <name>socache_shmcb</name>
        <userdefined config:type="boolean">true</userdefined>
      </module_entry>
      <module_entry>
        <change>enable</change>
        <name>reqtimeout</name>
        <userdefined config:type="boolean">true</userdefined>
      </module_entry>
      <module_entry>
        <change>enable</change>
        <name>authn_core</name>
        <userdefined config:type="boolean">true</userdefined>
      </module_entry>
      <module_entry>
        <change>enable</change>
        <name>authz_core</name>
        <userdefined config:type="boolean">true</userdefined>
      </module_entry>
    </modules>
    <service config:type="boolean">true</service>
    <version>2.9</version>
  </http-server>

List Name

List Elements

Description

Listen

List of host Listen settings

PORT

port address

ADDRESS

Network address. All addresses will be taken if this entry is empty.

hosts

List of Hosts configuration

KEY

Host name; <KEY>main</KEY> defines the main hosts, for example <KEY>192.168.43.2/secondserver.suse.de</KEY>

VALUE

List of different values describing the host.

modules

Module list. Only user defined modules need to be described.

name

Module name

userdefined

For historical reasons, it is always set to true.

change

For historical reasons, it is always set to enable.

Element

Description

Comment

version

Version of used Apache server

Only for information. Default 2.9

service

Enable Apache service

Optional. Default: false

Note
Note: Firewall

To run an Apache server correctly, make sure the firewall is configured appropriately.

4.23 Squid Server

Squid is a caching and forwarding Web proxy.

Example 4.40: Squid Server Configuration
  <squid>
    <acls config:type="list">
      <listentry>
        <name>QUERY</name>
        <options config:type="list">
          <option>cgi-bin \?</option>
        </options>
        <type>urlpath_regex</type>
      </listentry>
      <listentry>
        <name>apache</name>
        <options config:type="list">
          <option>Server</option>
          <option>^Apache</option>
        </options>
        <type>rep_header</type>
      </listentry>
      <listentry>
        <name>all</name>
        <options config:type="list">
          <option>0.0.0.0/0.0.0.0</option>
        </options>
        <type>src</type>
      </listentry>
      <listentry>
        <name>manager</name>
        <options config:type="list">
          <option>cache_object</option>
        </options>
        <type>proto</type>
      </listentry>
      <listentry>
        <name>localhost</name>
        <options config:type="list">
          <option>127.0.0.1/255.255.255.255</option>
        </options>
        <type>src</type>
      </listentry>
      <listentry>
        <name>to_localhost</name>
        <options config:type="list">
          <option>127.0.0.0/8</option>
        </options>
        <type>dst</type>
      </listentry>
      <listentry>
        <name>SSL_ports</name>
        <options config:type="list">
          <option>443</option>
        </options>
        <type>port</type>
      </listentry>
      <listentry>
        <name>Safe_ports</name>
        <options config:type="list">
          <option>80</option>
        </options>
        <type>port</type>
      </listentry>
      <listentry>
        <name>Safe_ports</name>
        <options config:type="list">
          <option>21</option>
        </options>
        <type>port</type>
      </listentry>
      <listentry>
        <name>Safe_ports</name>
        <options config:type="list">
          <option>443</option>
        </options>
        <type>port</type>
      </listentry>
      <listentry>
        <name>Safe_ports</name>
        <options config:type="list">
          <option>70</option>
        </options>
        <type>port</type>
      </listentry>
      <listentry>
        <name>Safe_ports</name>
        <options config:type="list">
          <option>210</option>
        </options>
        <type>port</type>
      </listentry>
      <listentry>
        <name>Safe_ports</name>
        <options config:type="list">
          <option>1025-65535</option>
        </options>
        <type>port</type>
      </listentry>
      <listentry>
        <name>Safe_ports</name>
        <options config:type="list">
          <option>280</option>
        </options>
        <type>port</type>
      </listentry>
      <listentry>
        <name>Safe_ports</name>
        <options config:type="list">
          <option>488</option>
        </options>
        <type>port</type>
      </listentry>
      <listentry>
        <name>Safe_ports</name>
        <options config:type="list">
          <option>591</option>
        </options>
        <type>port</type>
      </listentry>
      <listentry>
        <name>Safe_ports</name>
        <options config:type="list">
          <option>777</option>
        </options>
        <type>port</type>
      </listentry>
      <listentry>
        <name>CONNECT</name>
        <options config:type="list">
          <option>CONNECT</option>
        </options>
        <type>method</type>
      </listentry>
    </acls>
    <http_accesses config:type="list">
      <listentry>
        <acl config:type="list">
          <listentry>manager</listentry>
          <listentry>localhost</listentry>
        </acl>
        <allow config:type="boolean">true</allow>
      </listentry>
      <listentry>
        <acl config:type="list">
          <listentry>manager</listentry>
        </acl>
        <allow config:type="boolean">false</allow>
      </listentry>
      <listentry>
        <acl config:type="list">
          <listentry>!Safe_ports</listentry>
        </acl>
        <allow config:type="boolean">false</allow>
      </listentry>
      <listentry>
        <acl config:type="list">
          <listentry>CONNECT</listentry>
          <listentry>!SSL_ports</listentry>
        </acl>
        <allow config:type="boolean">false</allow>
      </listentry>
      <listentry>
        <acl config:type="list">
          <listentry>localhost</listentry>
        </acl>
        <allow config:type="boolean">true</allow>
      </listentry>
      <listentry>
        <acl config:type="list">
          <listentry>all</listentry>
        </acl>
        <allow config:type="boolean">false</allow>
      </listentry>
    </http_accesses>
    <http_ports config:type="list">
      <listentry>
        <host/>
        <port>3128</port>
        <transparent config:type="boolean">false</transparent>
      </listentry>
    </http_ports>
    <refresh_patterns config:type="list">
      <listentry>
        <case_sensitive config:type="boolean">true</case_sensitive>
        <max>10080</max>
        <min>1440</min>
        <percent>20</percent>
        <regexp>^ftp:</regexp>
      </listentry>
      <listentry>
        <case_sensitive config:type="boolean">true</case_sensitive>
        <max>1440</max>
        <min>1440</min>
        <percent>0</percent>
        <regexp>^gopher:</regexp>
      </listentry>
      <listentry>
        <case_sensitive config:type="boolean">true</case_sensitive>
        <max>4320</max>
        <min>0</min>
        <percent>20</percent>
        <regexp>.</regexp>
      </listentry>
    </refresh_patterns>
    <service_enabled_on_startup config:type="boolean">true</service_enabled_on_startup>
    <settings>
      <access_log config:type="list">
        <listentry>/var/log/squid/access.log</listentry>
      </access_log>
      <cache_dir config:type="list">
        <listentry>ufs</listentry>
        <listentry>/var/cache/squid</listentry>
        <listentry>100</listentry>
        <listentry>16</listentry>
        <listentry>256</listentry>
      </cache_dir>
      <cache_log config:type="list">
        <listentry>/var/log/squid/cache.log</listentry>
      </cache_log>
      <cache_mem config:type="list">
        <listentry>8</listentry>
        <listentry>MB</listentry>
      </cache_mem>
      <cache_mgr config:type="list">
        <listentry>webmaster</listentry>
      </cache_mgr>
      <cache_replacement_policy config:type="list">
        <listentry>lru</listentry>
      </cache_replacement_policy>
      <cache_store_log config:type="list">
        <listentry>/var/log/squid/store.log</listentry>
      </cache_store_log>
      <cache_swap_high config:type="list">
        <listentry>95</listentry>
      </cache_swap_high>
      <cache_swap_low config:type="list">
        <listentry>90</listentry>
      </cache_swap_low>
      <client_lifetime config:type="list">
        <listentry>1</listentry>
        <listentry>days</listentry>
      </client_lifetime>
      <connect_timeout config:type="list">
        <listentry>2</listentry>
        <listentry>minutes</listentry>
      </connect_timeout>
      <emulate_httpd_log config:type="list">
        <listentry>off</listentry>
      </emulate_httpd_log>
      <error_directory config:type="list">
        <listentry/>
      </error_directory>
      <ftp_passive config:type="list">
        <listentry>on</listentry>
      </ftp_passive>
      <maximum_object_size config:type="list">
        <listentry>4096</listentry>
        <listentry>KB</listentry>
      </maximum_object_size>
      <memory_replacement_policy config:type="list">
        <listentry>lru</listentry>
      </memory_replacement_policy>
      <minimum_object_size config:type="list">
        <listentry>0</listentry>
        <listentry>KB</listentry>
      </minimum_object_size>
    </settings>
  </squid>

Attribute

Values

Description

acls

List of Access Control Settings (ACLs).

Each list entry contains the name, type, and additional options. Use the YaST Squid configuration module to get an overview of possible entries.

http_accesses

In the Access Control table, access can be denied or allowed to ACL Groups.

If there are more ACL Groups in one definition, access will be allowed or denied to members who belong to all ACL Groups at the same time.

The Access Control table is checked in the order listed here. The first matching entry is used.

http_ports

Define all ports where Squid will listen for clients' HTTP requests.

Host can contain a host name or IP address or remain empty.

transparent disables PMTU discovery when transparent.

refresh_patterns

Refresh patterns define how Squid treats the objects in the cache.

The refresh patterns are checked in the order listed here. The first matching entry is used.

Min determines how long (in minutes) an object should be considered fresh if no explicit expiry time is given. Max is the upper limit of how long objects without an explicit expiry time will be considered fresh. Percent is the percentage of the object's age (time since last modification). An object without an explicit expiry time will be considered fresh.

settings

Map of all available general parameters with default values.

Use the YaST Squid configuration module to get an overview about possible entries.

service_enabled_on_startup

Squid service start when booting.

Value: true/false

4.24 FTP Server

Configure your FTP Internet server settings.

Example 4.41: FTP server configuration:
  <ftp-server>
    <AnonAuthen>2</AnonAuthen>
    <AnonCreatDirs>NO</AnonCreatDirs>
    <AnonMaxRate>0</AnonMaxRate>
    <AnonReadOnly>NO</AnonReadOnly>
    <AntiWarez>YES</AntiWarez>
    <Banner>Welcome message</Banner>
    <CertFile/>
    <ChrootEnable>NO</ChrootEnable>
    <EnableUpload>YES</EnableUpload>
    <FTPUser>ftp</FTPUser>
    <FtpDirAnon>/srv/ftp</FtpDirAnon>
    <FtpDirLocal/>
    <GuestUser/>
    <LocalMaxRate>0</LocalMaxRate>
    <MaxClientsNumber>10</MaxClientsNumber>
    <MaxClientsPerIP>3</MaxClientsPerIP>
    <MaxIdleTime>15</MaxIdleTime>
    <PasMaxPort>40500</PasMaxPort>
    <PasMinPort>40000</PasMinPort>
    <PassiveMode>YES</PassiveMode>
    <SSL>0</SSL>
    <SSLEnable>NO</SSLEnable>
    <SSLv2>NO</SSLv2>
    <SSLv3>NO</SSLv3>
    <StartDaemon>2</StartDaemon>
    <StartXinetd>YES</StartXinetd>
    <TLS>YES</TLS>
    <Umask/>
    <UmaskAnon/>
    <UmaskLocal/>
    <VerboseLogging>NO</VerboseLogging>
    <VirtualUser>NO</VirtualUser>
  </ftp-server>

Element

Description

Comment

AnonAuthen

Enable/disable anonymous and local users.

Authenticated Users Only: 1; Anonymous Only: 0; Both: 2

AnonCreatDirs

Anonymous users can create directories.

Values: YES/NO

AnonReadOnly

Anonymous users can upload.

Values: YES/NO

AnonMaxRate

The maximum data transfer rate permitted for anonymous clients.

KB/s

AntiWarez

Disallow downloading of files that were uploaded but not validated by a local admin.

Values: YES/NO

Banner

Specify the name of a file containing the text to display when someone connects to the server.

CertFile

DSA certificate to use for SSL-encrypted connections

This option specifies the location of the DSA certificate to use for SSL-encrypted connections.

ChrootEnable

When enabled, local users will be (by default) placed in a chroot jail in their home directory after login.

Warning: This option has security implications. Values: YES/NO

EnableUpload

If enabled, FTP users can upload.

To allow anonymous users to upload, enable AnonReadOnly. Values: YES/NO

FTPUser

Defining anonymous FTP user.

FtpDirAnon

FTP directory for anonymous users.

Specify a directory which is used for FTP anonymous users.

FtpDirLocal

FTP directory for authenticated users.

Specify a directory which is used for FTP authenticated users.

LocalMaxRate

The maximum data transfer rate permitted for local authenticated users.

KB/s

MaxClientsNumber

The maximum number of clients allowed to connect.

MaxClientsPerIP

Max clients for one IP.

The maximum number of clients allowed to connect from the same source Internet address.

MaxIdleTime

The maximum time (timeout) a remote client may wait between FTP commands.

Minutes

PasMaxPort

Maximum value for a port range for passive connection replies.

PassiveMode needs to be set to YES.

PasMinPort

Minimum value for a port range for passive connection replies.

PassiveMode needs to be set to YES.

PassiveMode

Enable Passive Mode

Value: YES/NO

SSL

Security Settings

Disable SSL/TLS: 0; Accept SSL and TLS: 1; Refuse Connections Without SSL/TLS: 2

SSLEnable

If enabled, SSL connections are allowed.

Value: YES/NO

SSLv2

If enabled, SSL version 2 connections are allowed.

Value: YES/NO

SSLv3

If enabled, SSL version 3 connections are allowed.

Value: YES/NO

StartDaemon

FTP daemon is started.

Manually: 0; when booting: 1; via xinetd: 2

StartXinetd

Has to be set to YES if StartDaemon is 2

Value: YES/NO

TLS

If enabled, TLS connections are allowed.

Value: YES/NO

Umask

File creation mask. (umask for files):(umask for directories).

For example 177:077 if you feel paranoid.

UmaskAnon

The value to which the umask for file creation is set for anonymous users.

To specify octal values, remember the "0" prefix, otherwise the value will be treated as a base 10 integer.

UmaskLocal

Umask for authenticated users.

To specify octal values, remember the "0" prefix, otherwise the value will be treated as a base 10 integer.

VerboseLogging

When enabled, all FTP requests and responses are logged.

Value: YES/NO

VirtualUser

By using virtual users, FTP accounts can be administrated without affecting system accounts.

Value: YES/NO

Note
Note: Firewall

Proper Firewall setting will be required for the FTP server to run correctly.

4.25 TFTP Server

Configure your TFTP Internet server settings.

Use this to enable a server for TFTP (trivial file transfer protocol). The server will be started using xinetd.

Note that TFTP and FTP are not the same.

Example 4.42: TFTP server configuration:
  <tftp-server>
    <start_tftpd config:type="boolean">true</start_tftpd>
    <tftp_directory>/tftpboot</tftp_directory>
  </tftp-server>

Element

Description

Comment

start_tftpd

Enabling TFTP server service.

Value: true/false

tftp_directory

Boot Image Directory: Specify the directory where served files are located.

The usual value is /tftpboot. The directory will be created if it does not exist. The server uses this as its root directory (using the -s option).

4.26 Firstboot Workflow

The YaST firstboot utility (YaST Initial System Configuration), which runs after the installation is completed, lets you configure the before creation of the install image. On the first boot after configuration, users are then guided through a series of steps that allow for easier configuration of their desktops. YaST firstboot does not run by default and needs to be configured to run.

Example 4.43: Enabling Firstboot Workflow
      <firstboot>
        <firstboot_enabled config:type="boolean">true</firstboot_enabled>
      </firstboot>

4.27 Security Settings

Using the features of this module, you can to change the local security settings on the target system. The local security settings include the boot configuration, login settings, password settings, user addition settings, and file permissions.

Configuring the security settings automatically is similar to the Custom Settings in the security module available in the running system. This allows you create a customized configuration.

Example 4.44: Security configuration

See the reference for the meaning and the possible values of the settings in the following example.

<security>
  <console_shutdown>ignore</console_shutdown>
  <displaymanager_remote_access>no</displaymanager_remote_access>
  <fail_delay>3</fail_delay>
  <faillog_enab>yes</faillog_enab>
  <gid_max>60000</gid_max>
  <gid_min>101</gid_min>
  <gdm_shutdown>root</gdm_shutdown>
  <lastlog_enab>yes</lastlog_enab>
  <encryption>md5</encryption>
  <obscure_checks_enab>no</obscure_checks_enab>
  <pass_max_days>99999</pass_max_days>
  <pass_max_len>8</pass_max_len>
  <pass_min_days>1</pass_min_days>
  <pass_min_len>6</pass_min_len>
  <pass_warn_age>14</pass_warn_age>
  <passwd_use_cracklib>yes</passwd_use_cracklib>
  <permission_security>secure</permission_security>
  <run_updatedb_as>nobody</run_updatedb_as>
  <uid_max>60000</uid_max>
  <uid_min>500</uid_min>
</security>

4.27.1 Password Settings Options

Change various password settings. These settings are mainly stored in the /etc/login.defs file.

Use this resource to activate one of the encryption methods currently supported. If not set, DES is configured.

DES, the Linux default method, works in all network environments, but it restricts you to passwords no longer than eight characters. MD5 allows longer passwords, thus provides more security, but some network protocols do not support this, and you may have problems with NIS. Blowfish is also supported.

Additionally, you can set up the system to check for password plausibility and length etc.

4.27.2 Boot Settings

Use the security resource, to change various boot settings.

How to interpret CtrlAltDel?

When someone at the console has pressed the CtrlAltDel key combination, the system usually reboots. Sometimes it is desirable to ignore this event, for example, when the system serves as both workstation and server.

Shutdown behavior of GDM

Configure a list of users allowed to shut down the machine from GDM.

4.27.3 Login Settings

Change various login settings. These settings are mainly stored in the /etc/login.defs file.

4.27.4 New user settings (useradd settings)

Set the minimum and maximum possible user and group ID

4.28 Linux Audit Framework (LAF)

This module allows the configuration of the audit daemon and to add rules for the audit subsystem.

Example 4.45: LAF configuration
  <audit-laf>
    <auditd>
      <flush>INCREMENTAL</flush>
      <freq>20</freq>
      <log_file>/var/log/audit/audit.log</log_file>
      <log_format>RAW</log_format>
      <max_log_file>5</max_log_file>
      <max_log_file_action>ROTATE</max_log_file_action>
      <name_format>NONE</name_format>
      <num_logs>4</num_logs>
    </auditd>
    <rules/>
  </audit-laf>

Attribute

Values

Description

auditd/flush

Describes how to write the data to disk.

If set to INCREMENTAL the Frequency parameter tells how many records to write before issuing an explicit flush to disk. NONE means: no special effort is made to flush data, DATA: keep data portion synchronized, SYNC: keep data and metadata fully synchronized.

auditd/freq

This parameter tells how many records to write before issuing an explicit flush to disk.

The parameter flush needs to be set to INCREMENTAL.

auditd/log_file

The full path name to the log file.

auditd/log_fomat

How much information needs to be logged.

Set RAW to log all data (store in a format exactly as the kernel sends it) or NOLOG to discard all audit information instead of writing it to disk (does not affect data sent to the dispatcher).

auditd/max_log_file

How much information needs to be logged.

Unit: Megabytes

auditd/num_logs

Number of log files.

max_log_file_action needs to be set to ROTATE

auditd/max_log_file_action

What happens if the log capacity has been reached.

If the action is set to ROTATE the Number of Log Files specifies the number of files to keep. Set to SYSLOG, the audit daemon will write a warning to /var/log/messages. With SUSPEND the daemon stops writing records to disk. IGNORE means do nothing, KEEP_LOGS is similar to ROTATE, but log files are not overwritten.

auditd/name_format

Computer Name Format describes how to write the computer name to the log file.

If USER is set, the User Defined Name is used. NONE means no computer name is inserted. HOSTNAME uses the name returned by the 'gethostname' syscall. FQD uses the fully qualified domain name.

rules

Rules for auditctl

You can edit the rules manually, which we only recommend for advanced users. For more information about all options, see man auditctl.

4.29 Users and Groups

AutoYaST supports defining local users, groups, special login settings and even default options for new users. Those settings are defined in the following sections:

users

List of users

user_defaults

Default options for new users

groups

List of groups

login_settings

Special login settings like password-less login or autologin

Note
Note: Users and groups set up during the first stage

Users and groups are set up during the first stage, so you can set up a usable system without running the second stage.

4.29.1 Users

A list of users can be defined in the <users> section. Take into account that at least the root users should be set up so you can log in after the installation is finished.

Example 4.46: Minimal User Configuration
<users config:type="list">
  <user>
    <username>root</username>
    <user_password>password</user_password>
    <encrypted config:type="boolean">false</encrypted>
  </user>
    <user>
    <username>tux</username>
    <user_password>password</user_password>
    <encrypted config:type="boolean">false</encrypted>
  </user>
</users>

The following example shows a more complex scenario. System wide default setting from /etc/default/useradd, such as the shell or the parent directory for the home directory, are applied.

Example 4.47: Complex User Configuration
<users config:type="list">
  <user>
    <username>root</username>
    <user_password>password</user_password>
    <uid>1001</uid>
    <gid>100</gid>
    <encrypted config:type="boolean">false</encrypted>
    <fullname>Root User</fullname>
    <authorized_keys config:type="list">
      <listentry>command="/opt/login.sh" ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDKLt1vnW2vTJpBp3VK91rFsBvpY97NljsVLdgUrlPbZ/L51FerQQ+djQ/ivDASQjO+567nMGqfYGFA/De1EGMMEoeShza67qjNi14L1HBGgVojaNajMR/NI2d1kDyvsgRy7D7FT5UGGUNT0dlcSD3b85zwgHeYLidgcGIoKeRi7HpVDOOTyhwUv4sq3ubrPCWARgPeOLdVFa9clC8PTZdxSeKp4jpNjIHEyREPin2Un1luCIPWrOYyym7aRJEPopCEqBA9HvfwpbuwBI5F0uIWZgSQLfpwW86599fBo/PvMDa96DpxH1VlzJlAIHQsMkMHbsCazPNC0++Kp5ZVERiH root@example.net</listentry>
    </authorized_keys>
  </user>
  <user>
    <username>tux</username>
    <user_password>password</user_password>
    <uid>1002</uid>
    <gid>100</gid>
    <encrypted config:type="boolean">false</encrypted>
    <fullname>Plain User</fullname>
    <home>/Users/plain</home>
    <password_settings>
      <max>120</max>
      <inact>5</inact>
    </password_settings>
  </user>
</users>
Note
Note: authorized_keys File will be overwritten

If the profile defines a set of SSH authorized keys for a user in the authorized_keys section, an existing $HOME/.ssh/authorized_keys file will be overwritten. If not existing, the file will be created with the content specified. Avoid overwriting an existing authorized_keys by not specifying the respective section in the AutoYaST control file.

Note
Note: Specifying a user ID (uid)

Each user on a Linux system has got a numeric user ID. You can either specify such a user ID within the AutoYaST control file manually by using uid, or let the system automatically choose a user ID by not using uid.

User IDs should be unique throughout the system. If not, some applications such as the login manager gdm may no longer work as expected.

When adding users with the AutoYaST control file, it is strongly recommended not to mix user defined IDs and automatically provided IDs. When doing so, unique IDs cannot be guaranteed. Either specify IDs for all users added with the AutoYaST control file or let the system choose the ID for all users.

Attribute

Values

Description

username

Text

<username>lukesw</username>

Required. It should be a valid user name. Check man 8 useradd if you are not sure.

fullname

Text

<fullname>Tux Torvalds</fullname>

Optional. User's fullname.

forename

Text

<forname>Tux</forename>

Optional. User's forename.

surname

Text

<surname>Skywalkwer</surname>

Optional. User's surname.

uid

Number

<uid>1001</uid>

Optional. User ID. It should be a unique and must be non-negative number. If not specified, AutoYaST will automatically choose a user ID. Also refer to Note: Specifying a user ID (uid) for additional information.

gid

Number

<gid>100</gid>

Optional. Initial group ID. It must be a unique and non-negative number. Moreover it must refer to an existing group.

home

Path

<home>/home/luke</home>

Optional. Absolute path to the user's home directory. By default, /home/username will be used (for example, alice's home directory will be /home/alice).

shell

Path

<shell>/usr/bin/zsh</shell>

Optional. /bin/bash is the default value. If you choose another one, make sure that it's installed (adding the corresponding package to the software section).

user_password

Text

<user_password>some-password</user_password>

Optional. User's password can be written in plain text (not recommended) or in encrypted form. Check encrypted to select the desired behavior.

encrypted

Boolean

<encrypted config:type="boolean">true</encrypted>

Optional. Considered false if not present. Indicates if the user's password in the profile is encrypted or not.

password_settings

Password settings

<password_settings>
  <expire/>
  <max>60</max>
  <warn>7</warn>
</password_settings>

Optional. Some password settings can be customized: expire (account expiration date in format YYYY-MM-DD), flag (/etc/shadow flag), inact (number of days after password expiration that account is disabled), max (maximum number of days a password is valid), min (grace period in days until which a user can change password after it has expired) and warn (number of days before expiration when the password change reminder starts).

authorized_keys

List of authorized keys

<authorized_keys config:type="list">
  <listentry>ssh-rsa ...</listentry>
</authorized_keys>

A list of authorized keys to be written to $HOME/.ssh/authorized_keys. See example below.

4.29.2 User Defaults

The profile can specify a set of default values for new users like password expiration, initial group, home directory prefix, etc. Besides using them as default values for the users that are defined in the profile, AutoYaST will write those settings to /etc/default/useradd to be read for useradd.

Attribute

Values

Description

group

Text

<group>100</group>

Optional. Default initial login group.

groups

Text

<groups>users</groups>

Optional. List of additional groups.

home

Path

<home>/home</home>

Optional. User's home directory prefix.

expire

Date

<expire>2017-12-31</expire>

Optional. Default password expiration date in YYYY-MM-DD format.

inactive

Number

<inactive>3</inactive>

Optional. Number of days after which an expired account is disabled.

no_groups

Boolean

<no_groups config:type="boolean">true</no_groups>

Optional. Do not use secondary groups.

shell

Path

<shell>/usr/bin/fish</shell>

Default login shell. /bin/bash is the default value. If you choose another one, make sure that it is installed (adding the corresponding package to the software section).

skel

Path

<skel>/etc/skel</skel>

Optional. Location of the files to be used as skel when adding a new user. You can find more information in man 8 useradd.

umask

File creation mode mask

<umask>022</umask>

Set the file creation mode mask for the home directory. By default useradd will use 022. Check man 8 useradd and man 1 umask for further information.

4.29.3 Groups

A list of groups can be defined in <groups> as shown in the example.

Example 4.48: Group Configuration
<groups>
  <group>
    <gid>100<gid>
    <groupname>users</groupname>
    <userlist>bob,alice</userlist>
  </group>
</groups>

Attribute

Values

Description

groupname

Text

<groupname>users</groupname>

Required. It should be a valid groupname. Check man 8 groupadd if you are not sure.

gid

Number

<gid>100</gid>

Optional. Group ID. It must be a unique and non-negative number.

group_password

Text

<group_password>password</group_password>

Optional. The group's password can be written in plain text (not recommended) or in encrypted form. Check the encrypted to select the desired behavior.

encrypted

Boolean

<encrypted config:type="boolean">true</encrypted>

Optional. Indicates if the group's password in the profile is encrypted or not.

userlist

Users list

<userlist>bob,alice</userlist>

Optional. A list of users who belong to the group. User names must be separated by commas.

4.29.4 Login Settings

Two special login settings can be enabled through an AutoYaST profile: autologin and password-less login. Both of them are disabled by default.

Example 4.49: Enabling autologin and password-less login
<login_settings>
  <autologin_user>vagrant</autologin_user>
  <password_less_login config:type="boolean">true</password_less_login>
</login_settings>

Attribute

Values

Description

password_less_login

Boolean

<password_less_login config:type="boolean">true</password_less_login>

Optional. Enables password-less login. It only affects graphical login.

autologin_user

Text

<autologin_user>alice</autologin_user>

Optional. Enables autologin for the given user.

4.30 Custom User Scripts

By adding scripts to the auto-installation process you can customize the installation according to your needs and take control in different stages of the installation.

In the auto-installation process, five types of scripts can be executed at different points in time during the installation:

All scripts need to be in the <scripts> section.

  • pre-scripts (very early, before anything else really happens)

  • postpartitioning-scripts (after partitioning and mounting to /mnt but before RPM installation)

  • chroot-scripts (after the package installation, before the first boot)

  • post-scripts (during the first boot of the installed system, no services running)

  • init-scripts (during the first boot of the installed system, all services up and running)

4.30.1 Pre-Install Scripts

Executed before YaST does any real change to the system (before partitioning and package installation but after the hardware detection).

You can use a pre-script to modify your control file and let AutoYaST reread it. Find your control file in /tmp/profile/autoinst.xml. Adjust the file and store the modified version in /tmp/profile/modified.xml. AutoYaST will read the modified file after the pre-script finishes.

It is also possible to change the partitioning in your pre-script.

Note
Note: Pre-Install Scripts with Confirmation

Pre-scripts are executed at an early stage of the installation. This means if you have requested to confirm the installation, the pre-scripts will be executed before the confirmation screen shows up (profile/install/general/mode/confirm).

Note
Note: Pre-Install and Zypper

To call zypper in the pre-install script you will need to set the environment variable ZYPP_LOCKFILE_ROOT="/var/run/autoyast" to prevent conflicts with the running YaST process.

Pre-Install Script elements must be placed as follows:

<scripts>
  <pre-scripts config:type="list">
    <script>
      ...
    </script>
  </pre-scripts>
</scripts>

4.30.2 Post-partitioning Scripts

Executed after YaST has done the partitioning and written the fstab. The empty system is already mounted to /mnt.

Post-partitioning script elements must be placed as follows:

<scripts>
  <postpartitioning-scripts config:type="list">
    <script>
      ...
    </script>
  </postpartitioning-scripts>
</scripts>

4.30.3 Chroot Environment Scripts

Chroot scripts are executed before the machine reboots for the first time. You can execute chroot scripts before the installation chroots into the installed system and configures the boot loader or you can execute a script after the chroot into the installed system has happened (look at the chrooted parameter for that).

Chroot Environment script elements must be placed as follows:

<scripts>
  <chroot-scripts config:type="list">
    <script>
      ...
    </script>
  </chroot-scripts>
</scripts>

4.30.4 Post-Install Scripts

These scripts are executed after AutoYaST has completed the system configuration and after it has booted the system for the first time.

It is possible to execute post scripts in an earlier phase while the installation network is still up and before AutoYaST configures the system. To run network-enabled post scripts, the boolean property network_needed needs to be set to true.

Post-install script elements must be placed as follows:

<scripts>
    <post-scripts config:type="list">
      <script>
        ...
      </script>
    </post-scripts>
  </scripts>

4.30.5 Init Scripts

These scripts are executed when YaST has finished, during the initial boot process after the network has been initialized. These final scripts are executed using /usr/lib/YaST2/bin/autoyast-initscripts.sh and are executed only once. Init scripts are configured using the tag init-scripts.

The following elements must be between the <scripts><init-scripts config:type="list"><script> ... </script></init-scripts>...</scripts> tags

Table 4.1: Init script XML representation

Element

Description

Comment

location

Define a location from where the script gets fetched. Locations can be the same as for the profile (HTTP, FTP, NFS, etc.).

<location
>http://10.10.0.1/myInitScript.sh</location>

Either <location> or <source> must be defined.

source

The script itself (source code), encapsulated in a CDATA tag. If you do not want to put the whole shell script into the XML profile, use the location parameter.

<source>
<![CDATA[
echo "Testing the init script" >
/tmp/init_out.txt
]]>
</source>

Either <location> or <source> must be defined.

filename

The file name of the script. It will be stored in a temporary directory under /tmp

<filename>mynitScript5.sh</filename>

Optional in case you only have a single init script. The default name (init-scripts) is used in this case. If having specified more than one init script, you must set a unique name for each script.

rerun

A script is only run once. Even if you use ayast_setup to run an XML file multiple times, the script is only run once. Change this default behavior by setting this boolean to true.

<rerun config:type="boolean">true</rerun>

Optional. Default is false (scripts only run once).

When added to the control file manually, scripts need to be included in a CDATA element to avoid confusion with the file syntax and other tags defined in the control file.

4.30.6 Script XML Representation

All XML elements described below can be used for each of the script types described above. The only exceptions are chrooted and network_needed—they are only valid for chroot and post-install scripts.

Table 4.2: Script XML Representation

Element

Description

Comment

location

Define a location from where the script gets fetched. Locations can be the same as for the control file (HTTP, FTP, NFS, etc.).

<location
>http://10.10.0.1/myPreScript.sh</location>

Either location or source must be defined.

source

The script itself (source code), encapsulated in a CDATA tag. If you do not want to put the whole shell script into the XML control file, refer to the location parameter.

<source>
<![CDATA[
echo "Testing the pre script" > /tmp/pre-script_out.txt
]]>
</source>

Either location or source must be defined.

interpreter

Specify the interpreter that must be used for the script. Supported options are shell and perl.

<interpreter>perl</interpreter>

Optional (default is shell).

file name

The file name of the script. It will be stored in a temporary directory under /tmp.

<filename>myPreScript5.sh</filename>

Optional. Default is the type of the script (pre-scripts in this case). If you have more than one script, you should define different names for each script.

feedback

If this boolean is true, output and error messages of the script (STDOUT and STDERR) will be shown in a pop-up. The user needs to confirm them via the OK button.

<feedback config:type="boolean">true</feedback>

Optional, default is false.

feedback_type

This can be message, warning or error. Set the timeout for these pop-ups in the <report> section.

<feedback_type>warning</feedback_type>

Optional, if missing, an always blocking pop-up is used.

debug

If this is true, every single line of a shell script is logged. Perl scripts are run with warnings turned on.

<debug config:type="boolean">true</debug>

Optional, default is true.

notification

This text will be shown in a pop-up for the time the script is running in the background.

<notification>Please wait while script is running...</notification>

Optional, if not configured, no notification pop-up will be shown.

param-list

It is possible to specify parameters given to the script being called. You may have more than one param entry. They are concatenated by a single space character on the script command line. If any shell quoting should be necessary (for example to protect embedded spaces) you need to include this.

<param-list>
  <param>par1</param>
  <param>par2 par3</param>
  <param>"par4.1 par4.2"</param>
</param-list>

Optional, if not configured, no parameters get passed to script.

rerun

A script is only run once. Even if you use ayast_setup to run an XML file multiple times, the script is only run once. Change this default behavior by setting this boolean to true.

<rerun config:type="boolean">true</rerun>

Optional, default is false (scripts only run once).

chrooted

If set to false, the installed system remains mounted at /mnt and no chroot happens. The boot loader is not installed either at this stage. Setting it to true means, a chroot into /mnt is performed, where the installed system is mounted. The boot loader is installed, and if you want to change anything in the installed system, you do not need to use the /mnt prefix anymore.

<chrooted config:type="boolean"
>true</chrooted>

Optional, default is false. This option is only available for chroot environment scripts.

network_needed

If set to false the script will run after the YaST modules like the user configuration and everything else are done. The network is configured but not up and running yet. With this value set to true, the script runs before all YaST modules are configured. So there is no local user and no network is configured but the installation network is still up and running (if you did a network installation).

<network_needed config:type="boolean"
>true</network_needed>

Optional, default is false. This option is only available for post-install scripts.

4.30.7 Script Example

Example 4.50: Script Configuration
<?xml version="1.0"?>
<!DOCTYPE profile>
<profile xmlns="http://www.suse.com/1.0/yast2ns" xmlns:config="http://www.suse.com/1.0/configns">
<scripts>
  <chroot-scripts config:type="list">
    <script>
      <chrooted config:type="boolean">true</chrooted>
      <filename>chroot.sh</filename>
      <interpreter>shell</interpreter>
      <source><![CDATA[
#!/bin/sh
echo "Testing chroot (chrooted) scripts"
ls
]]>
      </source>
    </script>
    <script>
      <filename>chroot.sh</filename>
        <interpreter>shell</interpreter>
        <source><![CDATA[
#!/bin/sh
echo "Testing chroot scripts"
df
cd /mnt
ls
]]>
        </source>
      </script>
    </chroot-scripts>
    <post-scripts config:type="list">
      <script>
        <filename>post.sh</filename>
        <interpreter>shell</interpreter>
        <source><![CDATA[
#!/bin/sh

echo "Running Post-install script"
systemctl start portmap
mount -a 192.168.1.1:/local /mnt
cp /mnt/test.sh /tmp
umount /mnt
]]>
        </source>
      </script>
      <script>
        <filename>post.pl</filename>
        <interpreter>perl</interpreter>
        <source><![CDATA[
#!/usr/bin/perl
print "Running Post-install script";

]]>
        </source>
      </script>
    </post-scripts>
    <pre-scripts config:type="list">
      <script>
        <interpreter>shell</interpreter>
        <location>http://192.168.1.1/profiles/scripts/prescripts.sh</location>
      </script>
      <script>
        <filename>pre.sh</filename>
        <interpreter>shell</interpreter>
        <source><![CDATA[
#!/bin/sh
echo "Running pre-install script"
]]>
        </source>
      </script>
    </pre-scripts>
    <postpartitioning-scripts config:type="list">
      <script>
        <filename>postpart.sh</filename>
        <interpreter>shell</interpreter>
        <debug config:type="boolean">false</debug>
        <feedback config:type="boolean">true</feedback>
        <source><![CDATA[
touch /mnt/testfile
echo Hi
]]>
        </source>
      </script>
    </postpartitioning-scripts>
  </scripts>
</profile>

After installation is finished, the scripts and the output logs can be found in the directory /var/adm/autoinstall. The scripts are located in the subdirectory scripts and the output logs in the log directory.

The log consists of the output produced when executing the shell scripts using the following command:

/bin/sh -x SCRIPT_NAME 2&>/var/adm/autoinstall/logs/SCRIPT_NAME.log

4.31 System Variables (Sysconfig)

Using the sysconfig resource, it is possible to define configuration variables in the sysconfig repository (/etc/sysconfig) directly. Sysconfig variables, offer the possibility to fine-tune many system components and environment variables exactly to your needs.

The following example shows how a variable can be set using the sysconfig resource.

Example 4.51: Sysconfig Configuration
<sysconfig config:type="list" >
  <sysconfig_entry>
    <sysconfig_key>XNTPD_INITIAL_NTPDATE</sysconfig_key>
    <sysconfig_path>/etc/sysconfig/xntp</sysconfig_path>
    <sysconfig_value>ntp.host.com</sysconfig_value>
  </sysconfig_entry>
  <sysconfig_entry>
    <sysconfig_key>HTTP_PROXY</sysconfig_key>
    <sysconfig_path>/etc/sysconfig/proxy</sysconfig_path>
    <sysconfig_value>proxy.host.com:3128</sysconfig_value>
  </sysconfig_entry>
  <sysconfig_entry>
    <sysconfig_key>FTP_PROXY</sysconfig_key>
    <sysconfig_path>/etc/sysconfig/proxy</sysconfig_path>
    <sysconfig_value>proxy.host.com:3128</sysconfig_value>
  </sysconfig_entry>
</sysconfig>

Both relative and absolute paths can be provided. If no absolute path is given, it is treated as a sysconfig file under the /etc/sysconfig directory.

4.32 Adding Complete Configurations

For many applications and services you may have a configuration file which should be copied to the appropriate location on the installed system. For example, if you are installing a Web server, you may have a server configuration file (httpd.conf).

Using this resource, you can embed the file into the control file by specifying the final path on the installed system. YaST will copy this file to the specified location.

This feature requires the autoyast2 package to be installed. If the package is missing, AutoYaST will automatically install the package if it is missing.

You can specify the file_location where the file should be retrieved from. This can also be a location on the network such as an HTTP server: <file_location>http://my.server.site/issue</file_location>.

You can create directories by specifying a file_path that ends with a slash.

Example 4.52: Dumping files into the installed system
<files config:type="list">
  <file>
    <file_path>/etc/apache2/httpd.conf</file_path>
    <file_contents>

<![CDATA[
some content
]]>

    </file_contents>
  </file>
  <file>
    <file_path>/mydir/a/b/c/</file_path> <!-- create directory -->
  </file>
</files>

A more advanced example is shown below. This configuration will create a file using the content supplied in file_contents and change the permissions and ownership of the file. After the file has been copied to the system, a script is executed. This can be used to modify the file and prepare it for the client's environment.

Example 4.53: Dumping files into the installed system
<files config:type="list">
  <file>
    <file_path>/etc/someconf.conf</file_path>
    <file_contents>

<![CDATA[
some content
]]>

    </file_contents>
    <file_owner>tux.users</file_owner>
    <file_permissions>444</file_permissions>
    <file_script>
      <interpreter>shell</interpreter>
      <source>

<![CDATA[
#!/bin/sh

echo "Testing file scripts" >> /etc/someconf.conf
df
cd /mnt
ls
]]>

      </source>
    </file_script>
  </file>
</files>

4.33 Ask the User for Values during Installation

You have the option to let the user decide the values of specific parts of the control file during the installation. If you use this feature, a pop-up will ask the user to enter a specific part of the control file during installation. If you want a full auto installation, but the user should set the password of the local account, you can do this via the ask directive in the control file.

The elements listed below must be placed within the following XML structure:

<general>
  <ask-list config:type="list">
    <ask>
      ...
    </ask>
  </ask-list>
</general>
Table 4.3: Ask the User for Values: XML representation

Element

Description

Comment

question

The question you want to ask the user.

<question>Enter the LDAP server</question>

The default value is the path to the element (the path often looks strange, so we recommend entering a question).

default

Set a preselection for the user. A text entry will be filled out with this value. A check box will be true or false and a selection will have the given value preselected.

<default>dc=suse,dc=de</default>

Optional.

help

An optional help text that is shown on the left side of the question.

<help>Enter the LDAP server address.</help>

Optional.

title

An optional title that is shown above the questions.

<title>LDAP server</title>

Optional.

type

The type of the element you want to change. Possible values are symbol, boolean, string and integer. The file system in the partition section is a symbol, while the encrypted element in the user configuration is a boolean. You can see the type of that element if you look in your control file at the config:type="...." attribute. You can also use static_text as type. A static_text is a text that does not require any user input and can be used to show information not included in the help text.

<type>symbol</type>

Optional. The default is string. If type is symbol, you must provide the selection element too (see below).

password

If this boolean is set to true, a password dialog pops up instead of a simple text entry. Setting this to true only makes sense if type is string.

<password config:type="boolean">true</password>

Optional. The default is false.

pathlist

A list of path elements. A path is a comma separated list of elements that describes the path to the element you want to change. For example, the LDAP server element can be found in the control file in the <ldap><ldap_server> section. So if you want to change that value, you need to set the path to ldap,ldap_server.

<pathlist config:type="list">
  <path>networking,dns,hostname</path>
  <path>...</path>
</pathlist>

To change the password of the first user in the control file, you need to set the path to users,0,user_password. The 0 indicates the first user in the <users config:type="list"> list of users in the control file. 1 would be the second one, and so on.

<users config:type="list">
  <user>
    <username>root</username>
    <user_password>password to change</user_password>
    <encrypted config:type="boolean">false</encrypted>
  </user>
  <user>
    <username>tux</username>
    <user_password>password to change</user_password>
    <encrypted config:type="boolean">false</encrypted>
  </user>
</users>

This information is optional but you should at least provide path or file.

file

You can store the answer to a question in a file, to use it in one of your scripts later. If you ask during stage=initial and you want to use the answer in stage 2, then you need to copy the answer-file in a chroot script that is running as chrooted=false. Use the command: cp /tmp/my_answer /mnt/tmp/. The reason is that /tmp in stage 1 is in the RAM disk and will be lost after the reboot, but the installed system is already mounted at /mnt/.

<file>/tmp/answer_hostname</file>

This information is optional, but you should at least provide path or file.

stage

Stage configures the installation stage in which the question pops up. You can set this value to cont or initial. initial means the pop-up comes up very early in the installation, shortly after the pre-script has run. cont means, that the dialog with the question comes after the first reboot when the system boots for the very first time. Questions you answer during the initial stage will write their answer into the control file on the hard disk. You should know that if you enter clear text passwords during initial. Of course it does not make sense to ask for the file system to use during the cont phase. The hard disk is already partitioned at that stage and the question will have no effect.

<stage>cont</stage>

Optional. The default is initial.

selection

The selection element contains a list of entry elements. Each entry represents a possible option for the user to choose. The user cannot enter a value in a text box, but he can choose from a list of values.

<selection config:type="list">
  <entry>
    <value>
        btrfs
    </value>
    <label>
        Btrfs File System
    </label>
  </entry>
  <entry>
    <value>
        ext3
    </value>
    <label>
        Extended3 File System
    </label>
  </entry>
</selection>

Optional for type=string, not possible for type=boolean and mandatory for type=symbol.

dialog

You can ask more than one question per dialog. To do so, specify the dialog-id with an integer. All questions with the same dialog-id belong to the same dialog. The dialogs are sorted by the id too.

<dialog config:type="integer">3</dialog>

Optional.

element

you can have more than one question per dialog. To make that possible you need to specify the element-id with an integer. The questions in a dialog are sorted by id.

<element config:type="integer">1</element>

Optional (see dialog).

width

You can increase the default width of dialog. If there are multiple width specifications per dialog, the largest one is used. The number is roughly equivalent to the number of characters.

<width config:type="integer">50</width>

Optional.

height

You can increase default height of dialog. If there are multiple height specifications per dialog, largest one is used. The number is roughly equivalent to number of lines.

<height config:type="integer">15</height>

Optional.

frametitle

You can have more than one question per dialog. Each question on a dialog has a frame that can have a frame title, a small caption for each question. You can put multiple elements into one frame. They need to have the same frame title.

<frametitle>User data</frametitle>

Optional. Default is no frame title.

script

You can run scripts after a question has been answered (see the table below for detailed instructions about scripts).

<script>...</script>

Optional (default is no script).

ok_label

You can change the label on the Ok button. The last element that specifies the label for a dialog wins.

<ok_label>Finish</ok_label>

Optional.

back_label

You can change the label on the Back button. The last element that specifies the label for a dialog wins.

<back_label>change values</back_label>

Optional.

timeout

You can specify an integer here that is used as timeout in seconds. If the user does not answer the question before the timeout, the default value is taken as answer. When the user touches or changes any widget in the dialog, the timeout is turned off and the dialog needs to be confirmed via Ok.

<timeout config:type="integer">30</timeout>

Optional. A missing value is interpreted as 0, which means that there is no timeout.

default_value_script

You can run scripts to set the default value for a question (see Section 4.33.1, “Default Value Scripts” for detailed instructions about default value scripts). This feature is useful if you can calculate a default value, especially in combination with the timeout option.

<default_value_script>...</default_value_script>

Optional. Default is no script.

4.33.1 Default Value Scripts

You can run scripts to set the default value for a question. This feature is useful if you can calculate a default value, especially in combination with the timeout option.

The elements listed below must be placed within the following XML structure:

<general>
  <ask-list config:type="list">
    <ask>
      <default_value_script>
        ...
      </default_value_script>
    </ask>
  </ask-list>
</general>
Table 4.4: Default Value Scripts: XML representation

Element

Description

Comment

source

The source code of the script. Whatever you echo to STDOUT will be used as default value for the ask-dialog. If your script has an exit code other than 0, the normal default element is used. Take care you use echo -n to suppress the \n and that you echo reasonable values and not okay for a boolean

<source>...</source>

This value is required, otherwise nothing would be executed.

interpreter

The interpreter to use.

<interpreter>perl</interpreter>

The default value is shell. You can also set /bin/myinterpreter as value.

4.33.2 Scripts

You can run scripts after a question has been answered.

The elements listed below must be placed within the following XML structure:

<general>
  <ask-list config:type="list">
    <ask>
      <script>
        ...
      </script>
    </ask>
  </ask-list>
</general>
Table 4.5: Scripts: XML representation

Element

Description

Comment

file name

The file name of the script.

<filename>my_ask_script.sh</filename>

The default is ask_script.sh

source

The source code of the script. Together with rerun_on_error activated, you check the value that was entered for sanity. Your script can create a file /tmp/next_dialog with a dialog id specifying the next dialog AutoYaST will raise. A value of -1 terminates the ask sequence. If that file is not created, AutoYaST will run the dialogs in the normal order (since 11.0 only).

<source>...</source>

This value is required, otherwise nothing would be executed.

environment

A boolean that passes the value of the answer to the question as an environment variable to the script. The variable is named VAL.

<environment config:type="boolean">true</environment>

Optional. Default is false.

feedback

A boolean that turns on feedback for the script execution. STDOUT will be displayed in a pop-up window that must be confirmed after the script execution.

<feedback config:type="boolean">true</feedback>

Optional, default is false.

debug

A boolean that turns on debugging for the script execution.

<debug config:type="boolean">true</debug>

Optional, default is true. This value needs feedback to be turned on, too.

rerun_on_error

A boolean that keeps the dialog open until the script has an exit code of 0 (zero). So you can parse and check the answers the user gave in the script and display an error with the feedback option.

<rerun_on_error config:type="boolean">true</rerun_on_error>

Optional, default is false. This value should be used together with the feedback option.

Below you can see an example of the usage of the ask feature.

<general>
  <ask-list config:type="list">
    <ask>
      <pathlist config:type="list">
        <path>ldap,ldap_server</path>
      </pathlist>
      <stage>cont</stage>
      <help>Choose your server depending on your department</help>
      <selection config:type="list">
        <entry>
          <value>ldap1.mydom.de</value>
          <label>LDAP for development</label>
        </entry>
        <entry>
          <value>ldap2.mydom.de</value>
          <label>LDAP for sales</label>
        </entry>
      </selection>
      <default>ldap2.mydom.de</default>
      <default_value_script>
        <source> <![CDATA[
echo -n "ldap1.mydom.de"
]]>
        </source>
      </default_value_script>
    </ask>
    <ask>
      <pathlist config:type="list">
        <path>networking,dns,hostname</path>
      </pathlist>
      <question>Enter Hostname</question>
      <stage>initial</stage>
      <default>enter your hostname here</default>
    </ask>
    <ask>
      <pathlist config:type="list">
        <path>partitioning,0,partitions,0,filesystem</path>
      </pathlist>
      <question>File System</question>
      <type>symbol</type>
      <selection config:type="list">
        <entry>
          <value config:type="symbol">reiser</value>
          <label>default File System (recommended)</label>
        </entry>
        <entry>
          <value config:type="symbol">ext3</value>
          <label>Fallback File System</label>
        </entry>
      </selection>
    </ask>
  </ask-list>
</general>

The following example shows a to choose between AutoYaST control files. AutoYaST will read the modified.xml file again after the ask-dialogs are done. This way you can fetch a complete new control file.

<general>
  <ask-list config:type="list">
    <ask>
      <selection config:type="list">
        <entry>
          <value>part1.xml</value>
          <label>Simple partitioning</label>
        </entry>
        <entry>
          <value>part2.xml</value>
          <label>encrypted /tmp</label>
        </entry>
        <entry>
          <value>part3.xml</value>
          <label>LVM</label>
        </entry>
      </selection>
      <title>XML Profile</title>
      <question>Choose a profile</question>
      <stage>initial</stage>
      <default>part1.xml</default>
      <script>
        <filename>fetch.sh</filename>
        <environment config:type="boolean">true</environment>
        <source>
<![CDATA[
wget http://10.10.0.162/$VAL -O /tmp/profile/modified.xml 2>/dev/null
]]>
        </source>
        <debug config:type="boolean">false</debug>
        <feedback config:type="boolean">false</feedback>
      </script>
    </ask>tion>
  </ask-list>
</general>

You can verify the answer of a question with a script like this:

<general>
  <ask-list config:type="list">
    <ask>
      <script>
        <filename>my.sh</filename>
        <rerun_on_error config:type="boolean">true</rerun_on_error>
        <environment config:type="boolean">true</environment>
        <source><![CDATA[
if [ "$VAL" = "myhost" ]; then
    echo "Illegal Hostname!";
    exit 1;
fi
exit 0
]]>
        </source>
        <debug config:type="boolean">false</debug>
        <feedback config:type="boolean">true</feedback>
      </script>
      <dialog config:type="integer">0</dialog>
      <element config:type="integer">0</element>
      <pathlist config:type="list">
        <path>networking,dns,hostname</path>
      </pathlist>
      <question>Enter Hostname</question>
      <default>enter your hostname here</default>
    </ask>
  </ask-list>
</general>

4.34 Kernel Dumps

Note
Note: Availability

This feature is not available on the IBM z Systems (s390x) architecture.

With Kdump the system can create crashdump files if the whole kernel crashes. Crash dump files contain the memory contents while the system crashed. Such core files can be analyzed later by support or a (kernel) developer to find the reason for the system crash. Kdump is mostly useful for servers where you cannot easily reproduce such crashes but it is important to get the problem fixed.

There is a downside to this. Enabling Kdump requires between 64 MB and 128 MB of additional system RAM reserved for Kdump in case the system crashes and the dump needs to be generated.

This section only describes how to set up Kdump with AutoYaST. It does not describe how Kdump works. For details, refer to the kdump(7) manual page.

The following example shows a general Kdump configuration.

Example 4.54: Kdump configuration
<kdump>
  <!-- memory reservation -->
  <add_crash_kernel config:type="boolean">true</add_crash_kernel>
  <crash_kernel>256M-:64M</crash_kernel>
  <general>

    <!-- dump target settings -->
    <KDUMP_SAVEDIR>ftp://stravinsky.suse.de/incoming/dumps</KDUMP_SAVEDIR>
    <KDUMP_COPY_KERNEL>true</KDUMP_COPY_KERNEL>
    <KDUMP_FREE_DISK_SIZE>64</KDUMP_FREE_DISK_SIZE>
    <KDUMP_KEEP_OLD_DUMPS>5</KDUMP_KEEP_OLD_DUMPS>

    <!-- filtering and compression -->
    <KDUMP_DUMPFORMAT>compressed</KDUMP_DUMPFORMAT>
    <KDUMP_DUMPLEVEL>1</KDUMP_DUMPLEVEL>

    <!-- notification -->
    <KDUMP_NOTIFICATION_TO>tux@example.com</KDUMP_NOTIFICATION_TO>
    <KDUMP_NOTIFICATION_CC>spam@example.com devnull@example.com</KDUMP_NOTIFICATION_CC>
    <KDUMP_SMTP_SERVER>mail.example.com</KDUMP_SMTP_SERVER>
    <KDUMP_SMTP_USER></KDUMP_SMTP_USER>
    <KDUMP_SMTP_PASSWORD></KDUMP_SMTP_PASSWORD>

    <!-- kdump kernel -->
    <KDUMP_KERNELVER></KDUMP_KERNELVER>
    <KDUMP_COMMANDLINE></KDUMP_COMMANDLINE>
    <KDUMP_COMMANDLINE_APPEND></KDUMP_COMMANDLINE_APPEND>

    <!-- expert settings -->
    <KDUMP_IMMEDIATE_REBOOT>yes</KDUMP_IMMEDIATE_REBOOT>
    <KDUMP_VERBOSE>15</KDUMP_VERBOSE>
    <KEXEC_OPTIONS></KEXEC_OPTIONS>
  </general>
</kdump>

4.34.1 Memory Reservation

The first step is to reserve memory for Kdump at boot-up. Because the memory must be reserved very early during the boot process, the configuration is done via a kernel command line parameter called crashkernel. The reserved memory will be used to load a second kernel which will be executed without rebooting if the first kernel crashes. This second kernel has a special initrd, which contains all programs necessary to save the dump over the network or to disk, send a notification e-mail, and finally reboot.

To reserve memory for Kdump, specify the amount (such as 64M to reserve 64 MB of memory from the RAM) and the offset. The syntax is crashkernel=AMOUNT@OFFSET. The kernel can auto-detect the right offset (except for the Xen hypervisor, where you need to specify 16M as offset). The amount of memory that needs to be reserved depends on architecture and main memory. Refer to Section 17.7.1, “Manual Kdump Configuration” for recommendations on the amount of memory to reserve for Kdump.

You can also use the extended command line syntax to specify the amount of reserved memory depending on the System RAM. That is useful if you share one AutoYaST control file for multiple installations or if you often remove or install memory on one machine. The syntax is:

BEGIN_RANGE_1-END_RANGE_1:AMOUNT_1,BEGIN_RANGE_2-END_RANGE_2:AMOUNT_2@OFFSET

BEGIN_RANGE_1 is the start of the first memory range (for example: 0M) and END_RANGE_1 is the end of the first memory range (can be empty in case infinity should be assumed) and so on. For example, 256M-2G:64M,2G-:128M reserves 64 MB of crashkernel memory if the system has between 256 MB and 2 GB RAM and reserves 128 MB of crashkernel memory if the system has more than 2 GB RAM.

On the other hand, it is possible to specify multiple values for crashkernel parameter. For example, when you need to reserve different segments of low and high memory, use values like 72M,low and 256M,high:

Example 4.55: Kdump memory reservation with multiple values
<kdump>
  <!-- memory reservation (high and low) -->
  <add_crash_kernel config:type="boolean">true</add_crash_kernel>
  <crash_kernel config:type="list">
    <listentry>72M,low</listentry>
    <listentry>256M,high</listentry>
  </crash_kernel>
</kdump>

The following table shows the settings necessary to reserve memory:

Table 4.6: Kdump Memory Reservation Settings:XML Representation

Element

Description

Comment

add_crash_kernel

Set to true if memory should be reserved and Kdump enabled.

<add_crash_kernel config:type="boolean">true</add_crash_kernel>

required

crash_kernel

Use the syntax of the crashkernel command line as discussed above.

<crash_kernel>256M:64M</crash_kernel>

A list of values is also supported.

<crash_kernel config:type="list">
  <listentry>72M,low</listentry>
  <listentry>256M,high</listentry>
</crash_kernel>

required

4.34.2 Dump Saving

4.34.2.1 Target

The element KDUMP_SAVEDIR specifies the URL to where the dump is saved. The following methods are possible:

  • file to save to the local disk,

  • ftp to save to an FTP server (without encryption),

  • sftp to save to an SSH2 SFTP server,

  • nfs to save to an NFS location and

  • cifs to save the dump to a CIFS/SMP export from Samba or Microsoft Windows.

For details see the kdump(5) manual page. Two examples are: file:///var/crash (which is the default location according to FHS) and ftp://user:password@host:port/incoming/dumps. A subdirectory, with the time stamp contained in the name, will be created and the dumps saved there.

When the dump is saved to the local disk, KDUMP_KEEP_OLD_DUMPS can be used to delete old dumps automatically. Set it to the number of old dumps that should be kept. If the target partition would end up with less free disk space than specified in KDUMP_FREE_DISK_SIZE, the dump is not saved.

To save the whole kernel and the debug information (if installed) to the same directory, set KDUMP_COPY_KERNEL to true. You will have everything you need to analyze the dump in one directory (except kernel modules and their debugging information).

4.34.2.2 Filtering and Compression

The kernel dump is uncompressed and unfiltered. It can get as large as your system RAM. To get smaller files, compress the dump file afterward. The dump needs to be decompressed before opening.

To use page compression, which compresses every page and allows dynamic decompression with the crash(8) debugging tool, set KDUMP_DUMPFORMAT to compressed (default).

You may not want to save all memory pages, for example those filled with zeroes. To filter the dump, set the KDUMP_DUMPLEVEL. 0 produces a full dump and 31 is the smallest dump. The manual pages kdump(5) and makedumpfile(8) list for each value which pages will be saved.

4.34.2.3 Summary

Table 4.7: Dump Target Settings: XML Representation

Element

Description

Comment

KDUMP_SAVEDIR

A URL that specifies the target to which the dump and related files will be saved.

<KDUMP_SAVEDIR>file:///var/crash/</KDUMP_SAVEDIR>

required

KDUMP_COPY_KERNEL

Set to true, if not only the dump should be saved to KDUMP_SAVEDIR but also the kernel and its debugging information (if installed).

<KDUMP_COPY_KERNEL>false</KDUMP_COPY_KERNEL>

optional

KDUMP_FREE_DISK_SIZE

Disk space in megabytes that must remain free after saving the dump. If not enough space is available, the dump will not be saved.

<KDUMP_FREE_DISK_SIZE>64</KDUMP_FREE_DISK_SIZE>

optional

KDUMP_KEEP_OLD_DUMPS

The number of dumps that are kept (not deleted) if KDUMP_SAVEDIR points to a local directory. Specify 0 if you do not want any dumps to be automatically deleted, specify -1 if all dumps except the current one should be deleted.

<KDUMP_KEEP_OLD_DUMPS>4</KDUMP_KEEP_OLD_DUMPS>

optional

4.34.3 E-Mail Notification

Configure e-mail notification if you want to be informed when a machine crashes and a dump is saved.

Because Kdump runs in the initrd, a local mail server cannot send the notification e-mail. An SMTP server needs to be specified (see below).

You need to provide exactly one address in KDUMP_NOTIFICATION_TO. More addresses can be specified in KDUMP_NOTIFICATION_CC. Only use e-mail addresses in both cases, not a real name.

Specify KDUMP_SMTP_SERVER and (if the server needs authentication) KDUMP_SMTP_USER and KDUMP_SMTP_PASSWORD. Support for TLS/SSL is not available but may be added in the future.

Table 4.8: E-Mail Notification Settings: XML Representation

Element

Description

Comment

KDUMP_NOTIFICATION_TO

Exactly one e-mail address to which the e-mail should be sent. Additional recipients can be specified in KDUMP_NOTIFICATION_CC.

<KDUMP_NOTIFICATION_TO
>tux@example.com</KDUMP_NOTIFICATION_TO>

optional (notification disabled if empty)

KDUMP_NOTIFICATION_CC

Zero, one or more recipients that are in the cc line of the notification e-mail.

<KDUMP_NOTIFICATION_CC
>wilber@example.com geeko@example.com</KDUMP_NOTIFICATION_CC>

optional

KDUMP_SMTP_SERVER

Host name of the SMTP server used for mail delivery. SMTP authentication is supported (see KDUMP_SMTP_USER and KDUMP_SMTP_PASSWORD) but TLS/SSL are not.

<KDUMP_SMTP_SERVER>email.suse.de</KDUMP_SMTP_SERVER>

optional (notification disabled if empty)

KDUMP_SMTP_USER

User name used together with KDUMP_SMTP_PASSWORD for SMTP authentication.

<KDUMP_SMTP_USER>bwalle</KDUMP_SMTP_USER>

optional

KDUMP_SMTP_PASSWORD

Password used together with KDUMP_SMTP_USER for SMTP authentication.

<KDUMP_SMTP_PASSWORD>geheim</KDUMP_SMTP_PASSWORD>

optional

4.34.4 Kdump Kernel Settings

As already mentioned, a special kernel is booted to save the dump. If you do not want to use the auto-detection mechanism to find out which kernel is used (see the kdump(5) manual page that describes the algorithm which is used to find the kernel), you can specify the version of a custom kernel in KDUMP_KERNELVER. If you set it to foo, then the kernel located in /boot/vmlinuz-foo or /boot/vmlinux-foo (in that order on platforms that have a vmlinuz file) will be used.

You can specify the command line used to boot the Kdump kernel. Normally the boot command line is used, minus settings that are not relevant for Kdump (like the crashkernel parameter) plus some settings needed by Kdump (see the manual page kdump(5)). To specify additional parameters, use KDUMP_COMMANDLINE_APPEND. If you know what you are doing and you want to specify the entire command line, set KDUMP_COMMANDLINE.

Table 4.9: Kernel Settings: XML Representation

Element

Description

Comment

KDUMP_KERNELVER

Version string for the kernel used for Kdump. Leave it empty to use the auto-detection mechanism (strongly recommended).

<KDUMP_KERNELVER
>2.6.27-default</KDUMP_KERNELVER>

optional (auto-detection if empty)

KDUMP_COMMANDLINE_APPEND

Additional command line parameters for the Kdump kernel.

<KDUMP_COMMANDLINE_APPEND
>console=ttyS0,57600</KDUMP_COMMANDLINE_APPEND>

optional

KDUMP_Command Line

Overwrite the automatically generated Kdump command line. Use with care. Usually, KDUMP_COMMANDLINE_APPEND should suffice.

<KDUMP_COMMANDLINE_APPEND
>root=/dev/sda5 maxcpus=1 irqpoll</KDUMP_COMMANDLINE>

optional

4.34.5 Expert Settings

Table 4.10: Expert Settings: XML Representations

Element

Description

Comment

KDUMP_IMMEDIATE_REBOOT

true if the system should be rebooted automatically after the dump has been saved, false otherwise. The default is to reboot the system automatically.

<KDUMP_IMMEDIATE_REBOOT
>true</KDUMP_IMMEDIATE_REBOOT>

optional

KDUMP_VERBOSE

Bitmask that specifies how verbose the Kdump process should be. Read kdump(5) for details.

<KDUMP_VERBOSE>3</KDUMP_VERBOSE>

optional

KEXEC_OPTIONS

Additional options that are passed to kexec when loading the Kdump kernel. Normally empty.

<KEXEC_OPTIONS>--noio</KEXEC_OPTIONS>

optional

4.35 DNS Server

The Bind DNS server can be configured by adding a dns-server resource. The three more straightforward properties of that resource can have a value of 1 to enable them or 0 to disable.

Attribute

Value

Description

chroot

0 / 1

The DNS server must be jailed in a chroot.

start_service

0 / 1

Bind is enabled (executed on system start).

use_ldap

0 / 1

Store the settings in LDAP instead of native configuration files.

Example 4.56: Basic DNS server settings
<dns-server>
  <chroot>0</chroot>
  <start_service>1</start_service>
  <use_ldap>0</use_ldap>
</dns-server>

In addition to those basic settings, there are three properties of type list that can be used to fine-tune the service configuration.

List

Description

logging

Options of the DNS server logging.

options

Bind options like the files and directories to use, the list of forwarders and other configuration settings.

zones

List of DNS zones known by the server, including all the settings, records and SOA records.

Example 4.57: Configuring DNS server zones and advanced settings
<dns-server>
  <logging config:type="list">
    <listentry>
      <key>channel</key>
      <value>log_syslog { syslog; }</value>
    </listentry>
  </logging>
  <options config:type="list">
    <option>
      <key>forwarders</key>
      <value>{ 10.10.0.1; }</value>
    </option>
  </options>
  <zones config:type="list">
    <listentry>
      <is_new>1</is_new>
      <modified>1</modified>
      <options config:type="list"/>
      <records config:type="list">
        <listentry>
          <key>mydom.uwe.</key>
          <type>MX</type>
          <value>0 mail.mydom.uwe.</value>
        </listentry>
        <listentry>
          <key>mydom.uwe.</key>
          <type>NS</type>
          <value>ns.mydom.uwe.</value>
        </listentry>
      </records>
      <soa>
        <expiry>1w</expiry>
        <mail>root.aaa.aaa.cc.</mail>
        <minimum>1d</minimum>
        <refresh>3h</refresh>
        <retry>1h</retry>
        <serial>2005082300</serial>
        <server>aaa.aaa.cc.</server>
        <zone>@</zone>
      </soa>
      <soa_modified>1</soa_modified>
      <ttl>2d</ttl>
      <type>master</type>
      <update_actions config:type="list">
        <listentry>
          <key>mydom.uwe.</key>
          <operation>add</operation>
          <type>NS</type>
          <value>ns.mydom.uwe.</value>
        </listentry>
      </update_actions>
      <zone>mydom.uwe</zone>
    </listentry>
  </zones>
</dns-server>

4.36 DHCP Server

The dhcp-server resource makes it possible to configure all the settings of a DHCP server by means of the six following properties.

Element

Value

Description

chroot

0 / 1

A value of 1 means that the DHCP server must be jailed in a chroot.

start_service

0 / 1

Set this to 1 to enable the DHCP server (that is, run it on system startup).

use_ldap

0 / 1

If set to 1, the settings will be stored in LDAP instead of native configuration files.

other_options

Text

String with parameters that will be passed to the DHCP server executable when started. For example, use "-p 1234" to listen on a non-standard 1234 port. For all possible options, consult the dhcpd manual page. If left blank, default values will be used.

allowed_interfaces

List

List of network cards in which the DHCP server will be operating. See the example below for the exact format.

settings

List

List of settings to configure the behavior of the DHCP server. The configuration is defined in a tree-like structure where the root represents the global options, with subnets and host nested from there. The children, parent_id and parent_type properties are used to represent that nesting. See the example below for the exact format.

Example 4.58: Example dhcp-server section
<dhcp-server>
  <allowed_interfaces config:type="list">
    <allowed_interface>eth0</allowed_interface>
  </allowed_interfaces>
  <chroot>0</chroot>
  <other_options>-p 9000</other_options>
  <start_service>1</start_service>
  <use_ldap>0</use_ldap>

  <settings config:type="list">
    <settings_entry>
      <children config:type="list"/>
      <directives config:type="list">
        <listentry>
          <key>fixed-address</key>
          <type>directive</type>
          <value>192.168.0.10</value>
        </listentry>
        <listentry>
          <key>hardware</key>
          <type>directive</type>
          <value>ethernet d4:00:00:bf:00:00</value>
        </listentry>
      </directives>
      <id>static10</id>
      <options config:type="list"/>
      <parent_id>192.168.0.0 netmask 255.255.255.0</parent_id>
      <parent_type>subnet</parent_type>
      <type>host</type>
    </settings_entry>
    <settings_entry>
      <children config:type="list">
        <child>
          <id>static10</id>
          <type>host</type>
        </child>
      </children>
      <directives config:type="list">
        <listentry>
          <key>range</key>
          <type>directive</type>
          <value>dynamic-bootp 192.168.0.100 192.168.0.150</value>
        </listentry>
        <listentry>
          <key>default-lease-time</key>
          <type>directive</type>
          <value>14400</value>
        </listentry>
        <listentry>
          <key>max-lease-time</key>
          <type>directive</type>
          <value>86400</value>
        </listentry>
      </directives>
      <id>192.168.0.0 netmask 255.255.255.0</id>
      <options config:type="list"/>
      <parent_id/>
      <parent_type/>
      <type>subnet</type>
    </settings_entry>
    <settings_entry>
      <children config:type="list">
        <child>
          <id>192.168.0.0 netmask 255.255.255.0</id>
          <type>subnet</type>
        </child>
      </children>
      <directives config:type="list">
        <listentry>
          <key>ddns-update-style</key>
          <type>directive</type>
          <value>none</value>
        </listentry>
        <listentry>
          <key>default-lease-time</key>
          <type>directive</type>
          <value>14400</value>
        </listentry>
      </directives>
      <id/>
      <options config:type="list"/>
      <parent_id/>
      <parent_type/>
      <type/>
    </settings_entry>
  </settings>
</dhcp-server>

4.37 SUSE Firewall

SUSE Firewall can be configured using the firewall resource. All the properties in this resource are optional and all of them are of type text (except the boolean start_firewall and enable_firewall properties).

4.37.1 General Firewall Configuration

The following properties are intended to configure the general settings of SUSE Firewall. Most of them are a direct representation of the corresponding setting at /etc/sysconfig/SuSEfirewall2. Check the comments in that file for further information.

Attribute

Value

Description

start_firewall

Boolean

Whether SUSE Firewall should be started right after applying the configuration.

enable_firewall

Boolean

Whether SUSE Firewall should be started on every system startup.

FW_LOG_ACCEPT_ALL

yes / no

Log every accepted package. If set to "yes" the value of FW_LOG_ACCEPT_CRIT becomes irrelevant.

FW_LOG_ACCEPT_CRIT

yes / no

Log accepted critical packages.

FW_LOG_DROP_ALL

yes / no

Log every dropped package. If set to "yes" the value of FW_LOG_DROP_CRIT becomes irrelevant.

FW_LOG_DROP_CRIT

yes / no

Log dropped critical packages.

FW_ALLOW_PING_FW

yes / no

Allow the firewall to reply to icmp echo requests.

FW_MASQUERADE

yes / no

Used to enable network masquerading, which allows to transparently redirect ports from one interface in the external zone to ports of another interface in a different zone. Masquerading needs at least one external interface and one other (not external) interface. Since routing is needed for masquerading, the values of this property and FW_ROUTE are connected.

FW_FORWARD_MASQ

Space delimited list of rules

Rules for network masquerading, with each rule following this format: source_network,ip_to_forward_to,protocol,port[,redirect_port,[destination_ip]]

FW_FORWARD_ALWAYS_INOUT_DEV

Space separated list of interface names

Bridge interfaces without IP address.

FW_IPSEC_TRUST

yes / no / int /ext / dmz

Trust level of IPsec packets.

FW_LOAD_MODULES

Space delimited list

Additional kernel modules to load at startup.

FW_ROUTE

yes / no

Whether routing between external, dmz and internal network should be activated. Related to FW_MASQUERADE.

FW_PROTECT_FROM_INT

yes / no / notrack

Whether to protect the firewall from the internal network.

4.37.2 Firewall Zones Configuration

The configuration of SUSE Firewall is based on the existence of three network zones. The behavior of each zone can be tweaked in several ways. Therefore, there are many almost equivalent AutoYaST properties that differs only by name and the zone to which they apply. For example, FW_DEV_DMZ for the demilitarized zone, FW_DEV_EXT for the external zone and FW_DEV_INT for the internal one.

Attributes

Value

Description

FW_ALLOW_FW_BROADCAST_{DMZ/EXT/INT}

yes / no

Allow IP broadcasts in that zone.

FW_CONFIGURATIONS_{DMZ/EXT/INT}

Space delimited list

Services that should be accessible from that zone.

FW_DEV_{DMZ/EXT/INT}

Space delimited list

Name of the interfaces that are considered to belong to the zone. The special keyword "any" means that packets arriving on interfaces not explicitly configured as int, ext or dmz will be considered to belong to this zone.

FW_IGNORE_FW_BROADCAST_{DMZ/EXT/INT}

yes / no

Suppress logging of dropped broadcast packets. Useful if you do not allow broadcasts on a LAN interface.

FW_SERVICES_ACCEPT_{DMZ/EXT/INT}

Space separated list of rules

Services to allow. Each rule following the format net,protocol[,dport[,sport[,flags]]]. For example, "0/0,tcp,22".

FW_SERVICES_ACCEPT_RELATED_{DMZ/EXT/INT}

Space delimited list of rules

Services to allow that are considered RELATED by the connection tracking engine. Format of each rule: net,protocol[,sport[,dport]]. For example, to allow Samba broadcast replies marked as related by nf_conntrack_netbios_ns from a certain network: "192.168.1.0/24,udp,137".

FW_SERVICES_{DMZ/EXT/INT}_IP

Space separated list

Which IP services should be accessible from the zone. Every entry in the list can be a port, a port range or a well known protocol name. This setting has precedence over FW_SERVICES_ACCEPT_*.

FW_SERVICES_{DMZ/EXT/INT}_RPC

Space delimited list

RPC services that should be accessible from the zone. This setting has precedence over FW_SERVICES_ACCEPT_*.

FW_SERVICES_{DMZ/EXT/INT}_TCP

Space separated list

Which TCP services should be accessible from the zone. Every entry in the list can be a port, a port range or a well known protocol name. This setting has precedence over FW_SERVICES_ACCEPT_*.

FW_SERVICES_{DMZ/EXT/INT}_UDP

Space separated list

Which UDP services should be accessible from the zone. Every entry in the list can be a port, a port range or a well known protocol name. This setting has precedence over FW_SERVICES_ACCEPT_*.

4.37.3 A Full Example

A full example of the firewall section, including general and zone specific properties could look like this.

Example 4.59: Example firewall section
<firewall>
  <FW_ALLOW_FW_BROADCAST_DMZ>no</FW_ALLOW_FW_BROADCAST_DMZ>
  <FW_ALLOW_FW_BROADCAST_EXT>no</FW_ALLOW_FW_BROADCAST_EXT>
  <FW_ALLOW_FW_BROADCAST_INT>no</FW_ALLOW_FW_BROADCAST_INT>
  <FW_DEV_DMZ></FW_DEV_DMZ>
  <FW_DEV_EXT>any eth0</FW_DEV_EXT>
  <FW_DEV_INT></FW_DEV_INT>
  <FW_FORWARD_ALWAYS_INOUT_DEV></FW_FORWARD_ALWAYS_INOUT_DEV>
  <FW_FORWARD_MASQ></FW_FORWARD_MASQ>
  <FW_IGNORE_FW_BROADCAST_DMZ>no</FW_IGNORE_FW_BROADCAST_DMZ>
  <FW_IGNORE_FW_BROADCAST_EXT>yes</FW_IGNORE_FW_BROADCAST_EXT>
  <FW_IGNORE_FW_BROADCAST_INT>no</FW_IGNORE_FW_BROADCAST_INT>
  <FW_IPSEC_TRUST>no</FW_IPSEC_TRUST>
  <FW_LOAD_MODULES>nf_conntrack_netbios_ns</FW_LOAD_MODULES>
  <FW_LOG_ACCEPT_ALL>no</FW_LOG_ACCEPT_ALL>
  <FW_LOG_ACCEPT_CRIT>yes</FW_LOG_ACCEPT_CRIT>
  <FW_LOG_DROP_ALL>no</FW_LOG_DROP_ALL>
  <FW_LOG_DROP_CRIT>yes</FW_LOG_DROP_CRIT>
  <FW_MASQUERADE>no</FW_MASQUERADE>
  <FW_PROTECT_FROM_INT>no</FW_PROTECT_FROM_INT>
  <FW_ROUTE>no</FW_ROUTE>
  <enable_firewall config:type="boolean">true</enable_firewall>
  <start_firewall config:type="boolean">true</start_firewall>
</firewall>

4.38 Miscellaneous Hardware and System Components

In addition to the core component configuration, like network authentication and security, AutoYaST offers a wide range of hardware and system configuration options, the same as available by default on any system installed manually and in an interactive way. For example, it is possible to configure printers, sound devices, TV cards and any other hardware components which have a module within YaST.

Any new configuration options added to YaST will be automatically available in AutoYaST.

4.38.1 Printer

AutoYaST support for printing is limited to basic settings defining how CUPS is used on a client for printing via the network.

There is no AutoYaST support for setting up local print queues. Modern printers are usually connected via USB. CUPS accesses USB printers by a model-specific device URI like usb://ACME/FunPrinter?serial=1a2b3c. Usually it is not possible to predict the correct USB device URI in advance, because it is determined by the CUPS back-end usb during runtime. Therefore it is not possible to set up local print queues with AutoYaST.

Basics on how CUPS is used on a client workstation to print via network:

On client workstations application programs submit print jobs to the CUPS daemon process (cupsd). cupsd forwards the print jobs to a CUPS print server in the network where the print jobs are processed. The server sends the printer specific data to the printer device.

If there is only a single CUPS print server in the network, there is no need to have a CUPS daemon running on each client workstation. Instead it is simpler to specify the CUPS server in /etc/cups/client.conf and access it directly (only one CUPS server entry can be set). In this case application programs that run on client workstations submit print jobs directly to the specified CUPS print server.

Example 4.60, “Printer configuration” shows a printer configuration section. The cupsd_conf_content entry contains the whole verbatim content of the cupsd configuration file /etc/cups/cupsd.conf. The client_conf_content entry contains the whole verbatim content of /etc/cups/client.conf. The printer section contains the cupsd configuration but it does not specify whether the cupsd should run.

Example 4.60: Printer configuration
  <printer>
    <client_conf_content>
      <file_contents><![CDATA[
... verbatim content of /etc/cups/client.conf ...
]]></file_contents>
    </client_conf_content>
    <cupsd_conf_content>
      <file_contents><![CDATA[
... verbatim content of /etc/cups/cupsd.conf ...
]]></file_contents>
    </cupsd_conf_content>
  </printer>
Note
Note: /etc/cups/cups-files.conf

With release 1.6 the CUPS configuration file has been split into two files: cupsd.conf and cups-files.conf. As of SUSE Linux Enterprise Server 12 SP3, AutoYaST only supports modifying cupsd.conf since the default settings in cups-files.conf are sufficient for usual printing setups.

4.38.2 Sound devices

An example of the sound configuration created using the configuration system is shown below.

Example 4.61: Sound configuration
<sound>
  <autoinstall config:type="boolean">true</autoinstall>
  <modules_conf config:type="list">
    <module_conf>
      <alias>snd-card-0</alias>
      <model>M5451, ALI</model>
      <module>snd-ali5451</module>
      <options>
        <snd_enable>1</snd_enable>
        <snd_index>0</snd_index>
        <snd_pcm_channels>32</snd_pcm_channels>
      </options>
    </module_conf>
  </modules_conf>
  <volume_settings config:type="list">
    <listentry>
      <Master config:type="integer">75</Master>
    </listentry>
  </volume_settings>
</sound>

4.39 Importing SSH Keys and Configuration

YaST allows to import SSH keys and server configuration from previous installations. The behavior of this feature can also be controlled through an AutoYaST profile.

Example 4.62: Importing SSH Keys and Configuration from /dev/sda2
<ssh_import>
  <import config:type="boolean">true</import>
  <copy_config config:type="boolean">true</copy_config>
  <device>/dev/sda2</device>
</ssh_import>

Attributes

Value

Description

import

true / false

SSH keys will be imported. If set to false, nothing will be imported.

copy_config

true / false

Additionally, SSH server configuration will be imported. This setting will not have effect if import is set to false.

device

Partition

Partition to import keys and configuration from. If it is not set, the partition which contains the most recently accessed key is used.

4.40 Configuration Management

AutoYaST allows delegating part of the configuration to a configuration management tool like Salt:

  • AutoYaST takes care of system installation (partitioning, network setup, etc.)

  • System configuration can be delegated to a configuration management tool

This module configures the connection to a configuration management tool and uploads SSH keys which are needed for establishing connections. At the end of the installation, the configuration management Master will be contacted to retrieve state files and other resources.

Example 4.63: Configuring Salt Manager
<configuration_management>
    <type>salt</type>
    <master>linux-addc</master>
    <auth_attempts config:type="integer">5</auth_attempts>
    <auth_time_out config:type="integer">10</auth_time_out>
    <keys_url>http://keys.example.de/keys</keys_url>
</configuration_management>

Attributes

Value

Description

type

Configuration management type

Configuration management name. Currently only salt is supported.

master

Host name

Host name or IP address of the configuration management master.

auth_attempts

Integer

At the end of installation, YaST connects to the configuration management master with maximum auth_attempts attempts. The default is 3 attempts.

auth_time_out

Integer

Time between the configuration management master connection attempts. The default is 15 seconds.

keys_url

URL of used key

Path to an HTTP server, hard disk, USB drive or similar with the files default.key and default.pub. This key has to be known to the configuration management master.

enable_services

True/false

Enables the configuration management services on the client side. Default is true.

5 Rules and Classes

5.1 Rules-based Automatic Installation

Rules offer the possibility to configure a system depending on system attributes by merging multiple control files during installation. The rules-based installation is controlled by a rules file. This is useful to install, for example, systems in two departments in one go. Assume a scenario where machines in department A need to be installed as office desktops, whereas machines in department B need to be installed as developer workstations. You would create a rules file with two different rules. For each rule, you could use different system parameters to distinguish the installations from one another. Each rule would also contain a link to an appropriate profile for each department.

The rules file is an XML file containing rules for each group of systems (or single systems) that you want to automatically install. A set of rules distinguish a group of systems based on one or more system attributes. After passing all rules, each group of systems is linked to a control file. Both the rules file and the control files must be located in a pre-defined and accessible location.

The rules file is retrieved only if no specific control file is supplied using the autoyast keyword. For example, if the following is used, the rules file will not be evaluated:

autoyast=http://10.10.0.1/profile/myprofile.xml
autoyast=http://10.10.0.1/profile/rules/rules.xml

Instead use:

autoyast=http://10.10.0.1/profile/

which will load http://10.10.0.1/profile/rules/rules.xml (the slash at the end of the directory name is important).

Rules
Figure 5.1: Rules

If more than one rule applies, the final control file for each group is generated on the fly using a merge script. The merging process is based on the order of the rules and later rules override configuration data in earlier rules. Note that the names of the top sections in the merged xml files need to be in alphabetical order for the merge to succeed.

The use of a rules file is optional. If the rules file is not found, system installation proceeds in the standard way by using the supplied control file or by searching for the control file depending on the MAC or the IP address of the system.

5.1.1 Rules File Explained

Example 5.1: Simple Rules File

The following simple example illustrates how the rules file is used to retrieve the configuration for a client with known hardware.

<?xml version="1.0"?>
<!DOCTYPE autoinstall>
<autoinstall xmlns="http://www.suse.com/1.0/yast2ns" xmlns:config="http://www.suse.com/1.0/configns">
  <rules config:type="list">
    <rule>
       <disksize>
            <match>/dev/sdc 1000</match>
            <match_type>greater</match_type>
       </disksize>
       <result>
            <profile>department_a.xml</profile>
            <continue config:type="boolean">false</continue>
        </result>
    </rule>
    <rule>
       <disksize>
            <match>/dev/sda 1000</match>
            <match_type>greater</match_type>
       </disksize>
       <result>
            <profile>department_b.xml</profile>
            <continue config:type="boolean">false</continue>
        </result>
    </rule>
  </rules>
</autoinstall>

The last example defines two rules and provides a different control file for every rule. The rule used in this case is disksize. After parsing the rules file, YaST attempts to match the target system with the rules in the rules.xml file. A rule match occurs when the target system matches all system attributes defined in the rule. When the system matches a rule, the respective resource is added to the stack of control files AutoYaST will use to create the final control file. The continue property tells AutoYaST whether it should continue with other rules after a match has been found.

If the first rule does not match, the next rule in the list is examined until a match is found.

Using the disksize attribute, you can provide different configurations for systems with hard disks of different sizes. The first rule checks if the device /dev/sdc is available and if it is greater than 1 GB in size using the match property.

A rule must have at least one attribute to be matched. If you need to check more attributes, such as memory or architectures, you can add more attributes in the rule resource as shown in the next example.

Example 5.2: Simple Rules File

The following example illustrates how the rules file is used to retrieve the configuration for a client with known hardware.

<?xml version="1.0"?>
<!DOCTYPE autoinstall>
<autoinstall xmlns="http://www.suse.com/1.0/yast2ns" xmlns:config="http://www.suse.com/1.0/configns">
  <rules config:type="list">
    <rule>
       <disksize>
            <match>/dev/sdc 1000</match>
            <match_type>greater</match_type>
       </disksize>
       <memsize>
            <match>1000</match>
            <match_type>greater</match_type>
       </memsize>
       <result>
            <profile>department_a.xml</profile>
            <continue config:type="boolean">false</continue>
        </result>
    </rule>
    <rule>
       <disksize>
            <match>/dev/shda 1000</match>
            <match_type>greater</match_type>
       </disksize>
       <memsize>
            <match>256</match>
            <match_type>greater</match_type>
       </memsize>
       <result>
            <profile>department_b.xml</profile>
            <continue config:type="boolean">false</continue>
        </result>
    </rule>
  </rules>
</autoinstall>

The rules directory must be located in the same directory specified via the autoyast keyword at boot time. If the client was booted using autoyast=http://10.10.0.1/profiles/, AutoYaST will search for the rules file at http://10.10.0.1/profiles/rules/rules.xml.

5.1.2 Custom Rules

If the attributes AutoYaST provides for rules are not enough for your purposes, use custom rules. Custom rules contain a shell script. The output of the script (STDOUT, STDERR is ignored) can be evaluated.

Here is an example for the use of custom rules:

<rule>
  <custom1>
    <script>
if grep -i intel /proc/cpuinfo > /dev/null; then
echo -n "intel"
else
echo -n "non_intel"
fi;
    </script>
    <match>*</match>
    <match_type>exact</match_type>
  </custom1>
  <result>
    <profile>@custom1@.xml</profile>
    <continue config:type="boolean">true</continue>
  </result>
</rule>

The script in this rule can echo either intel or non_intel to STDOUT (the output of the grep command must be directed to /dev/null in this case). The output of the rule script will be filled between the two '@' characters, to determine the file name of the control file to fetch. AutoYaST will read the output and fetch a file with the name intel.xml or non_intel.xml. This file can contain the AutoYaST profile part for the software selection; for example, in case you want a different software selection on intel hardware than on others.

The number of custom rules is limited to five. So you can use custom1 to custom5.

5.1.3 Match Types for Rules

You can use five different match_types:

  • exact (default)

  • greater

  • lower

  • range

  • regex (a simple =~ operator like in Bash)

If using exact, the string must match exactly as specified. regex can be used to match substrings like ntel will match Intel, intel and intelligent. greater and lower can be used for memsize or totaldisk for example. They can match only with rules that return an integer value. A range is only possible for integer values too and has the form of value1-value2, for example 512-1024.

5.1.4 Combine Attributes

Multiple attributes can be combined via a logical operator. It is possible to let a rule match if disksize is greater than 1GB or memsize is exactly 512MB.

You can do this with the operator element in the rules.xml file. and and or are possible operators, and being the default. Here is an example:

<rule>
  <disksize>
    <match>/dev/sda 1000</match>
    <match_type>greater</match_type>
  </disksize>
  <memsize>
    <match>256</match>
    <match_type>greater</match_type>
  </memsize>
  <result>
    <profile>machine2.xml</profile>
    <continue config:type="boolean">false</continue>
  </result>
  <operator>or</operator>
</rule>

5.1.5 Rules File Structure

The rules.xml file needs to:

  • have at least one rule,

  • have the name rules.xml,

  • be located in the directory rules in the profile repository,

  • have at least one attribute to match in the rule.

5.1.6 Predefined System Attributes

The following table lists the predefined system attributes you can match in the rules file.

If you are unsure about a value on your system, run /usr/lib/YaST/bin/y2base ayast_probe ncurses. The text box displaying the detected values can be scrolled. Note that this command will not work while another YaST process that requires a lock (for example the installer) is running. Therefore you cannot run it during the installation.

Table 5.1: System Attributes

Attribute

Values

Description

hostaddress

IP address of the host

This attribute must always match exactly.

host name

The name of the host

This attribute must always match exactly.

domain

Domain name of host

This attribute must always match exactly.

installed_product

The name of the product to be installed.

This attribute must always match exactly.

installed_product_version

The version of the product to be installed.

This attribute must always match exactly.

network

network address of host

This attribute must always match exactly.

mac

MAC address of host

This attribute must always match exactly (the MAC addresses should have the form 0080c8f6484c).

linux

Number of installed Linux partitions on the system

This attribute can be 0 or more.

others

Number of installed non-Linux partitions on the system

This attribute can be 0 or more.

xserver

X Server needed for graphic adapter

This attribute must always match exactly.

memsize

Memory available on host in MBytes

All match types are available.

totaldisk

Total disk space available on host in MBytes

All match types are available.

hostid

Hex representation of the IP address

Exact match required

arch

Architecture of host

Exact match required

karch

Kernel Architecture of host (for example SMP kernel, Xen kernel)

Exact match required

disksize

Drive device and size

All match types are available.

product

The hardware product name as specified in SMBIOS

Exact match required

product_vendor

The hardware vendor as specified in SMBIOS

Exact match required

board

The system board name as specified in SMBIOS

Exact match required

board_vendor

The system board vendor as specified in SMBIOS

Exact match required

custom1-5

Custom rules using shell scripts

All match types are available.

5.1.7 Rules with Dialogs

You can use dialog pop-ups with check boxes to select rules you want matched.

The elements listed below must be placed within the following XML structure in the rules.xml file:

<rules config:type="list">
  <rule>
    <dialog>
      ...
    </dialog>
  </rule>
</rules>

Attribute

Values

Description

dialog_nr

All rules with the same dialog_nr are presented in the same pop-up dialog. The same dialog_nr can appear in multiple rules.

<dialog_nr config:type="integer">3</dialog_nr>

This element is optional and the default for a missing dialog_nr is always 0. To use one pop-up for all rules, you do not need to specify the dialog_nr.

element

Specify a unique ID. Even if you have more than one dialog, you must not use the same id twice. Using id 1 on dialog 1 and id 1 on dialog 2 is not supported. (This behavior is contrary to the ask dialog, where you can have the same ID for multiple dialogs.)

<element config:type="integer">3</element>

Optional. If left out, AutoYaST adds its own ids internally. Then you cannot specify conflicting rules (see below).

title

Caption of the pop-up dialog

<title>Desktop Selection</title>

Optional

question

Question shown in the pop-up behind the check box.

<question>GNOME Desktop</question>

Optional. If you do not configure a text here, the name of the XML file that is triggered by this rule will be shown instead.

timeout

Timeout in seconds after which the dialog will automatically press the okay button. Useful for a non-blocking installation in combination with rules dialogs.

<timeout config:type="integer">30</timeout>

Optional. A missing timeout will stop the installation process until the dialog is confirmed by the user.

conflicts

A list of element ids (rules) that conflict with this rule. If this rule matches or is selected by the user, all conflicting rules are deselected and disabled in the pop-up. Take care that you do not create deadlocks.

<conflicts config:type="list">
  <element config:type="integer">1</element>
  <element config:type="integer">5</element>
  ...
</conflicts>

optional

Here is an example of how to use dialogs with rules:

<rules config:type="list">
  <rule>
    <custom1>
      <script>
echo -n 100
      </script>
      <match>100</match>
      <match_type>exact</match_type>
    </custom1>
    <result>
      <profile>rules/gnome.xml</profile>
      <continue config:type="boolean">true</continue>
    </result>
    <dialog>
      <element config:type="integer">0</element>
      <question>GNOME Desktop</question>
      <title>Desktop Selection</title>
      <conflicts config:type="list">
        <element config:type="integer">1</element>
      </conflicts>
      <dialog_nr config:type="integer">0</dialog_nr>
    </dialog>
  </rule>
  <rule>
    <custom1>
      <script>
echo -n 100
      </script>
      <match>101</match>
      <match_type>exact</match_type>
    </custom1>
    <result>
      <profile>rules/gnome.xml</profile>
      <continue config:type="boolean">true</continue>
    </result>
    <dialog>
      <element config:type="integer">1</element>
      <dialog_nr config:type="integer">0</dialog_nr>
      <question>Gnome Desktop</question>
      <conflicts config:type="list">
        <element config:type="integer">0</element>
      </conflicts>
    </dialog>
  </rule>
  <rule>
    <custom1>
      <script>
echo -n 100
      </script>
      <match>100</match>
      <match_type>exact</match_type>
    </custom1>
    <result>
      <profile>rules/all_the_rest.xml</profile>
      <continue config:type="boolean">false</continue>
    </result>
  </rule>
</rules>

5.2 Classes

Classes represent configurations for groups of target systems. Unlike rules, classes need to be configured in the control file. Then classes can be assigned to target systems.

Here is an example of a class definition:

<classes config:type="list">
  <class>
    <class_name>TrainingRoom</class_name>
    <configuration>Software.xml</configuration>
  </class>
</classes>

In the example above, the file Software.xml must be placed in the subdirectory classes/TrainingRoom/ It will be fetched from the same place the AutoYaST control file and rules were fetched from.

If you have multiple control files and those control files share parts, better use classes for common parts. You can also use XIncludes.

Using the configuration management system, you can define a set of classes. A class definition consists of the following variables:

  • Name: class name

  • Description:

  • Order: order (or priority) of the class in the stack of migration

Defining Classes
Figure 5.2: Defining Classes

You can create as many classes as you need, however it is recommended to keep the set of classes as small as possible to keep the configuration system concise. For example, the following sets of classes can be used:

  • site: classes describing a physical location or site,

  • machine: classes describing a type of machine,

  • role: classes describing the function of the machine,

  • group: classes describing a department or a group within a site or a location.

A file saved in a class directory can have the same syntax and format as a regular control file but represents a subset of the configuration. For example, to create a new control file for a computer with a specific network interface, you only need the control file resource that controls the configuration of the network. Having multiple network types, you can merge the one needed for a special type of hardware with other class files and create a new control file which suits the system being installed.

5.3 Mixing Rules and Classes

It is possible to mix rules and classes during an auto-installation session. For example you can identify a system using rules which contain class definitions in them. The process is described in the figure Figure A.1, “Rules Retrieval Process”.

After retrieving the rules and merging them, the generated control file is parsed and checked for class definitions. If classes are defined, then the class files are retrieved from the original repository and a new merge process is initiated.

5.4 Merging of Rules and Classes

With classes and with rules, multiple XML files get merged into one resulting XML file. This merging process is often confusing for people, because it behaves different than one would expect. First of all, it is important to note that the names of the top sections in the merged XML files must to be in alphabetical order for the merge to succeed.

For example, the following two XML parts should be merged:

<partitioning config:type="list">
  <drive>
    <partitions config:type="list">
      <partition>
        <filesystem config:type="symbol">swap</filesystem>
        <format config:type="boolean">true</format>
        <mount>swap</mount>
        <partition_id config:type="integer">130</partition_id>
        <size>2000mb</size>
      </partition>
      <partition>
        <filesystem config:type="symbol">xfs</filesystem>
        <partition_type>primary</partition_type>
        <size>4Gb</size>
        <mount>/data</mount>
      </partition>
    </partitions>
  </drive>
</partitioning>
<partitioning config:type="list">
  <drive>
    <initialize config:type="boolean">false</initialize>
    <partitions config:type="list">
      <partition>
        <format config:type="boolean">true</format>
        <filesystem config:type="symbol">xfs</filesystem>
        <mount>/</mount>
        <partition_id config:type="integer">131</partition_id>
        <partition_type>primary</partition_type>
        <size>max</size>
      </partition>
    </partitions>
    <use>all</use>
  </drive>
</partitioning>

You might expect the control file to contain 3 partitions. This is not the case. You will end up with two partitions and the first partition is a mix up of the swap and the root partition. Settings configured in both partitions, like mount or size, will be used from the second file. Settings that only exist in the first or second partition, will be copied to the merged partition too.

In this example, you do not want a second drive. The two drives should be merged into one. With regard to partitions, three separate ones should be defined. Using the dont_merge method solves the merging problem:

<classes config:type="list">
  <class>
    <class_name>swap</class_name>
    <configuration>largeswap.xml</configuration>
    <dont_merge config:type="list">
      <element>partition</element>
    </dont_merge>
  </class>
</classes>
<rule>
  <board_vendor>
    <match>ntel</match>
    <match_type>regex</match_type>
  </board_vendor>
  <result>
    <profile>classes/largeswap.xml</profile>
    <continue config:type="boolean">true</continue>
    <dont_merge config:type="list">
      <element>partition</element>
    </dont_merge>
  </result>
  <board_vendor>
    <match>PowerEdge [12]850</match>
    <match_type>regex</match_type>
  </board_vendor>
  <result>
    <profile>classes/smallswap.xml</profile>
    <continue config:type="boolean">true</continue>
    <dont_merge config:type="list">
      <element>partition</element>
    </dont_merge>
  </result>
</rule>

6 The Auto-Installation Process

6.1 Introduction

After the system has booted into an automatic installation and the control file has been retrieved, YaST configures the system according to the information provided in the control file. All configuration settings are summarized in a window that is shown by default and should be deactivated if a fully automatic installation is needed.

By the time YaST displays the summary of the configuration, YaST has only probed hardware and prepared the system for auto-installation. Nothing has been changed in the system yet. In case of any error, you can still abort the process.

A system should be automatically installable without the need to have any graphic adapter or monitor. Having a monitor attached to the client machine is nevertheless recommended so you can supervise the process and to get feedback in case of errors. Choose between the graphical and the text-based Ncurses interfaces. For headless clients, system messages can be monitored using the serial console.

6.1.1 X11 Interface (graphical)

This is the default interface while auto-installing. No special variables are required to activate it.

6.1.2 Serial console

Start installing a system using the serial console by adding the keyword console (for example console=ttyS0) to the command line of the kernel. This starts linuxrc in console mode and later YaST in serial console mode.

6.1.3 Text-based YaST Installation

This option can also be activated on the command line. To start YaST in text mode, add textmode=1 on the command line.

Starting YaST in the text mode is recommended when installing a client with less than 64 MB or when X11 should not be configured, especially on headless machines.

6.2 Choosing the Right Boot Medium

There are different methods for booting the client. The computer can boot from its network interface card (NIC) to receive the boot images via DHCP or TFTP. Alternatively a suitable kernel and initrd image can be loaded from a flash disk or a bootable DVD-ROM.

YaST will check for autoinst.xml in the root directory of the boot medium or the initrd upon start-up and switch to an automated installation if it was found. In case the control file is named differently or located elsewhere, specify its location on the kernel command line with the parameter AutoYaST=URL.

6.2.1 Booting from a Flash Disk

For testing/rescue purposes or because the NIC does not have a PROM or PXE you can build a bootable flash disk to use with AutoYaST. Flash disks can also store the control file.

Tip
Tip: Creating a Bootable Flash Disk

To create a bootable flash disk, copy either the SUSE Linux Enterprise Server iso image of DVD1 or the Mini CD ISO image to the disk using the dd command (the flash disk must not be mounted, all data on the device will be erased):

dd if=PATH_TO_ISO_IMAGE of=USB_STORAGE_DEVICE bs=4M

6.2.2 Booting from DVD-ROM

You can use the original SUSE Linux Enterprise Server DVD-ROM number one in combination with other media. For example, the control file can be provided via a flash disk or a specified location on the network. Alternatively, create a customized DVD-ROM that includes the control file.

6.2.3 Booting via PXE over the Network

Booting via PXE requires a DHCP and a TFTP server in your network. The computer will then boot without a physical medium. For instructions on setting up the required infrastructure, see Chapter 10, Remote Installation.

If you do installation via PXE, the installation will run into an endless loop. This happens because after the first reboot, the machine performs the PXE boot again and restarts the installation instead of booting from the hard disk for the second stage of the installation.

There are several ways to solve this problem. You can use an HTTP server to provide the AutoYaST control file. Alternatively, instead of a static control file, run a CGI script on the Web server that provides the control file and changes the TFTP server configuration for your target host. This way, the next PXE boot of the machine will be from the hard disk by default.

Another way is to use AutoYaST to upload a new PXE boot configuration for the target host via the control file:

<pxe>
  <pxe_localboot config:type="boolean">true</pxe_localboot>
  <pxelinux-config>
    DEFAULT linux
    LABEL linux
    localboot 0
  </pxelinux-config>
  <tftp-server>192.168.1.115</tftp-server>
  <pxelinux-dir>/pxelinux.cfg</pxelinux-dir>
  <filename>__MAC__</filename>
</pxe>

This entry will upload a new configuration for the target host to the TFTP server shortly before the first reboot happens. In most installations the TFTP daemon runs as user nobody. You need to make sure this user has write permissions to the pxelinux.cfg directory. You can also configure the file name that will be uploaded. If you use the magic __MAC__ file name, the file name will be the MAC address of your machine like, for example 01-08-00-27-79-49-ee. If the file name setting is missing, the IP address will be used for the file name.

To do another auto-installation on the same machine, you need to remove the file from the TFTP server.

6.3 Invoking the Auto-Installation Process

6.3.1 Command Line Options

Adding the command line variable autoyast causes linuxrc to start in automated mode. linuxrc searches for a configuration file, which should be distinguished from the main control file in the following places:

  • in the root directory of the initial RAM disk used for booting the system,

  • in the root directory of the boot medium

The configuration file used by linuxrc can have the following keywords (for a detailed description of how linuxrc works and other keywords, see Appendix C, Advanced Linuxrc Options):

Table 6.1: Keywords for linuxrc

Keyword

Value

autoupgrade

Initiate an automatic upgrade using AutoYaST. Also requires the autoyast parameter (see Table 6.2, “Command Line Variables for AutoYaST” for details).

autoyast

Location of the control file for automatic installation, see Table 6.2, “Command Line Variables for AutoYaST” for details.

autoyast2

Location of the control file for automatic installation. Similar to autoyast option but linuxrc parses the provided value and, for example, tries to configure a network when needed. For information about differences between the AutoYaST and linuxrc URI syntax, see the documentation of linuxrc. AutoYaST's rules and classes are not supported.

ifcfg

Configure and start the network. Required if the AutoYaST is to be fetched from a remote location. See Section C.3, “Advanced Network Setup” for details.

insmod

Kernel modules to load

install

Location of the installation directory, for example install=nfs://192.168.2.1/CDs/.

instmode

Installation mode, for example nfs, http etc. (not needed if install is set).

server

Server (NFS) to contact for source directory

serverdir

Directory on NFS Server

y2confirm

Even with <confirm>no</confirm> in the control file, the confirm proposal comes up.

These variables and keywords will bring the system up to the point where YaST can take over with the main control file. Currently, the source medium is automatically discovered, which in some cases makes it possible to initiate the auto-install process without giving any instructions to linuxrc.

The traditional linuxrc configuration file (info) has the function of giving the client enough information about the installation server and the location of the sources. Usually, this file is not required; but it is needed in special network environments where DHCP and BOOTP are not used or when special kernel modules need to be loaded.

All linuxrc keywords can be passed to linuxrc using the kernel command line. The command line can also be set when creating network bootable images or it can be passed to the kernel using a specially configured DHCP server in combination with Etherboot or PXE.

The command line variable autoyast can be used in the format described in table Table 6.2, “Command Line Variables for AutoYaST”

Table 6.2: Command Line Variables for AutoYaST

Command line variable

Description

autoyast=default

Default auto-installation option.

autoyast=file:///PATH

Looks for control file in specified path (relative to the source root directory, for example file:///autoinst.xml if in the top directory of a CD-ROM and you did an installation from CD).

autoyast=device://DEVICE/FILENAME

Looks for control file on a storage device. Do not specify the full path to the device, but the device name only. You may also omit specifying the device and trigger AutoYaST to search all devices (autoyast=device:///FILENAME).

autoyast=nfs://SERVER/PATH

Looks for control file on an NFS server.

autoyast=http://[user:password@]SERVER/PATH

Retrieves the control file from a Web server using the HTTP protocol. Specifying a user name and a password is optional.

autoyast=https://[user:password@]SERVER/PATH

Retrieves the control file from a Web server using HTTPS. Specifying a user name and a password is optional.

autoyast=tftp://SERVER/PATH

Retrieve the control file via TFTP.

autoyast=ftp://[user:password@]SERVER/PATH

Retrieve the control file via FTP. Specifying a user name and a password is optional.

autoyast=usb://PATH

Retrieve the control file from USB devices (AutoYaST will search all connected USB devices).

autoyast=relurl://PATH

Retrieve the control file from the installation source (install=....).

autoyast=slp

Query the location of the control file from an SLP server (service:autoyast:...). Optionally you may add a description= attribute so you can translate the URL into something more readable. (autoyast=slp:/?descr=*SLES*

autoyast=cifs://SERVER/PATH

Looks for control file on a CIFS server.

autoyast=label://LABEL/PATH

Searches for a control file on a device with the specified label

Several scenarios for auto-installation are possible using different types of infrastructure and source media. The simplest way is to use the source media (DVD number one) of SUSE Linux Enterprise Server. But to initiate the auto-installation process, the auto-installation command-line variable should be entered at system boot-up and the control file should be accessible for YaST.

In a scripting context, you can use a serial console for your virtual machine, that allows you to work in text mode. Then you can pass the needed parameters from an expect script or equivalent.

The following list of scenarios explains how the control file can be supplied:

Using the Original SUSE Linux Enterprise Server DVD-ROM

When using the original DVD-ROM (DVD #1 is needed), the control file needs to be accessible via flash disk or network:

Flash Disk.  Access the control file via the autoyast=usb://PATH option.

Network.  Access the control file via the following commands: autoyast=nfs://.., autoyast=ftp://.., autoyast=http://.., autoyast=https://.., autoyast=tftp://.., or autoyast=cifs://...

Using a Custom DVD-ROM

In this case, you can include the control file directly on the DVD-ROM. When placing it in the root directory and naming it autoinst.xml, it will automatically be found and used for the installation. Otherwise use autoyast=file:///PATH to specify the path to the control file.

When using a DVD-ROM for auto-installation, it is necessary to instruct the installer to use the DVD-ROM for installation instead of trying to find the installation files on the network. This can be done by adding the instmode=cd option to the kernel command line (this can be automated by adding the option to the isolinux.cfg file on the DVD).

Using a Network Installation Source

This option is the most important one because installations of multiple machines are usually done using SLP or NFS servers and other network services like BOOTP and DHCP. The easiest way to make the control file available is to place it in the root directory of the installation source naming it autoinst.xml. In this case it will automatically be found and used for the installation. The control file can also reside in the following places:

Flash Disk.  Access the control file via the autoyast=usb://PATH option.

Network.  Access the control file via the following commands: autoyast=nfs://.., autoyast=ftp://.., autoyast=http://.., autoyast=https://.., autoyast=tftp://.., or autoyast=cifs://...

Note
Note: Disabling Network and DHCP

To disable the network during installations where it is not needed or unavailable, for example when auto-installing from DVD-ROMs, use the linuxrc option netsetup=0 to disable the network setup.

Note
Note: Difference between the autoyast and autoyast2 Options

The options autoyast and autoyast2 are very similar but differ in one important point:

  • When you use autoyast=http://..., you need to provide linuxrc with the network configuration.

  • When you use autoyast2=http://..., linuxrc tries to configure the network for you.

If autoyast=default is defined, YaST will look for a file named autoinst.xml in the following three places:

  1. the root directory of the flash disk,

  2. the root directory of the installation medium,

  3. the root directory of the initial RAM disk used to boot the system.

With all AutoYaST invocation options, excluding default, it is possible to specify the location of the control file in the following ways:

  1. Specify the exact location of the control file:

    autoyast=http://192.168.1.1/control-files/client01.xml
  2. Specify a directory where several control files are located:

    autoyast=http://192.168.1.1/control-files/

    In this case the relevant control file is retrieved using the hex digit representation of the IP as described below.

If only the path prefix variable is defined, YaST will fetch the control file from the specified location in the following way:

  1. First, it will search for the control file using its own IP address in uppercase hexadecimal, for example 192.0.2.91 -> C000025B.

  2. If this file is not found, YaST will remove one hex digit and try again. This action is repeated until the file with the correct name is found. Ultimately, it will try looking for a file with the MAC address of the client as the file name (mac should have the following syntax: 0080C8F6484C) and if not found a file named default (in lowercase).

As an example, for 192.0.2.91, the HTTP client will try:

C000025B
C000025
C00002
C0000
C000
C00
C0
C
0080C8F6484C
default

in that order.

To determine the hex representation of the IP address of the client, use the utility called /usr/bin/gethostip available with the syslinux package.

Example 6.1: Determine HEX code for an IP address
# /usr/bin/gethostip 10.10.0.1
10.10.0.1 10.10.0.1 0A0A0001

6.3.2 Auto-installing a Single System

The easiest way to auto-install a system without any network connection is to use the original SUSE Linux Enterprise Server DVD-ROMs and a flash disk. You do not need to set up an installation server nor the network environment.

Create the control file and name it autoinst.xml. Copy the file autoinst.xml to the flash disk.

6.3.3 Combining the linuxrc info file with the AutoYaST control file

If you choose to pass information to linuxrc using the info file, it is possible to integrate the keywords in the XML control file. In this case the file needs to be accessible to linuxrc and needs to be named info.

Linuxrc will look for a string (start_linuxrc_conf in the control file which represents the beginning of the file. If it is found, it will parse the content starting from that string and will finish when the string end_linuxrc_conf is found. The options are stored in the control file in the following way:

Example 6.2: Linuxrc options in the control file
....
  <install>
....
    <init>
      <info_file>
<![CDATA[
#
# Do not remove the following line:
# start_linuxrc_conf
#
install: nfs://192.168.1.1/CDs/full-i386
textmode: 1
autoyast: file:///info

# end_linuxrc_conf
# Do not remove the above comment
#
]]>

      </info_file>
    </init>
......
  </install>
....

Note that the autoyast keyword must point to the same file. If it is on a flash disk, then the option usb:/// needs to be used. If the info file is stored in the initial RAM disk, the file:// option needs to be used.

6.4 System Configuration

The system configuration during auto-installation is the most important part of the whole process. As you have seen in the previous chapters, almost anything can be configured automatically on the target system. In addition to the pre-defined directives, you can always use post-scripts to change other things in the system. Additionally you can change any system variables, and if required, copy complete configuration files into the target system.

6.4.1 Post-Install and System Configuration

The post-installation and system configuration are initiated directly after the last package is installed on the target system and continue after the system has booted for the first time.

Before the system is booted for the first time, AutoYaST writes all data collected during installation and writes the boot loader in the specified location. In addition to these regular tasks, AutoYaST executes the chroot-scripts as specified in the control file. Note that these scripts are executed while the system is not yet mounted.

If a different kernel than the default is installed, a hard reboot will be required. A hard reboot can also be forced during auto-installation, independent of the installed kernel. Use the reboot property of the general resource (see Section 4.1, “General Options”).

6.4.2 System Customization

Most of the system customization is done in the second stage of the installation. If you require customization that cannot be done using AutoYaST resources, use post-install scripts for further modifications.

You can define an unlimited number of custom scripts in the control file, either by editing the control file or by using the configuration system.

7 Running AutoYaST in an Installed System

In some cases it is useful to run AutoYaST in a running system.

In the following example, an additional software package (foo) is going to be installed. To run this software, a user needs to be added and an NTP client needs to be configured.

The respective AutoYaST profile needs to include a section for the package installation (Section 4.9.6, “Installing Packages in Stage 2”), a user (Section 4.29.1, “Users”) section and an NTP-client (Section 4.20, “NTP Client”) section:

<?xml version="1.0"?>
<!DOCTYPE profile>
<profile xmlns="http://www.suse.com/1.0/yast2ns" xmlns:config="http://www.suse.com/1.0/configns">
  <ntp-client>
    <peers config:type="list">
      <peer>
        <address>us.pool.ntp.org</address>
        <comment/>
        <options> iburst</options>
        <type>server</type>
      </peer>
    </peers>
    <start_at_boot config:type="boolean">true</start_at_boot>
    <start_in_chroot config:type="boolean">false</start_in_chroot>
    <sync_interval config:type="integer">5</sync_interval>
    <synchronize_time config:type="boolean">false</synchronize_time>
  </ntp-client>
  <software>
    <post-packages config:type="list">
      <package>ntp</package>
      <package>yast2-ntp-client</package>
      <package>foo</package>
    </post-packages>
  </software>
  <users config:type="list">
    <user>
      <encrypted config:type="boolean">false</encrypted>
      <fullname>Foo user</fullname>
      <gid>100</gid>
      <home>/home/foo</home>
      <password_settings>
        <expire/>
        <flag/>
        <inact/>
        <max>99999</max>
        <min>0</min>
        <warn>7</warn>
      </password_settings>
      <shell>/bin/bash</shell>
      <uid>1001</uid>
      <user_password>linux</user_password>
      <username>foo</username>
    </user>
  </users>
</profile>

Store this file as /tmp/install_foo.xml and start the AutoYaST installation process by calling:

yast2 ayast_setup setup filename=/tmp/install_foo.xml dopackages="yes"

For more information, run yast2 ayast_setup longhelp

A Handling Rules

The following figure illustrates how rules are handled and the processes of retrieval and merge.

Rules Retrieval Process
Figure A.1: Rules Retrieval Process

B AutoYaST FAQ - Frequently Asked Questions

How do I invoke an AutoYaST installation?

On all SUSE Linux Enterprise Server versions, the automatic installation gets invoked by adding autoyast=<PATH_TO_PROFILE> to the kernel parameter list. So for example adding autoyast=http://MYSERVER/MYCONFIG.xml will start an automatic installation where the profile with the AutoYaST configuration gets fetched from the Web server myserver. See Section 6.3, “Invoking the Auto-Installation Process” for more information.

What is an AutoYaST profile?

A profile is the AutoYaST configuration file. The content of the AutoYaST profile determines how the system will be configured and which packages will get installed. This includes partitioning, network setup, and software sources, to name but a few. Almost everything that can be configured with YaST in a running system can also be configured in an AutoYaST profile. The profile format is an ASCII XML file.

How do I create an AutoYaST profile?

The easiest way to create an AutoYaST profile is to use an existing SUSE Linux Enterprise Server system as a template. On an already installed system, start YaST › Miscellaneous › Autoinstallation. Now select Tools › Create Reference Profile from the menu. Choose the system components you want to include in the profile. Alternatively, create a profile containing the complete system configuration by running sudo yast clone_system from the command line.

Both methods will create the file /root/autoinst.xml. The version created on the command line can be used to set up an identical clone of the system on which the profile was created. However, usually you will want to adjust the file to make it possible to install several machines that are very similar, but not identical. This can be done by adjusting the profile using your favorite text/XML editor.

How can I check the syntax of a created AutoYaST profile?

The most efficient way to check your created AutoYaST profile is by using jing or xmllint.

See Section 3.3, “Creating/Editing a Control File Manually” for details.

What is smallest AutoYaST profile that makes sense?

If a section has not been defined in the AutoYaST profile the settings of the general YaST installation proposal will be used. However, you need to specify at least the root password to be able to log in to the machine after the installation.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE profile>
<profile xmlns="http://www.suse.com/1.0/yast2ns" xmlns:config="http://www.suse.com/1.0/configns">
  <users config:type="list">
    <user>
      <encrypted config:type="boolean">false</encrypted>
      <user_password>linux</user_password>
      <username>root</username>
    </user>
  </users>
</profile>
How do I do an automatic installation with autodetection of my sound card?

Use the following sound section in your profile:

<sound>
  <autoinstall config:type="boolean">true</autoinstall>
  <configure_detected config:type="boolean">true</configure_detected>
</sound>
I want to install from DVD only. Where do I put the AutoYaST profile?

Put the profile in the root of the DVD. Refer to it with file:///PROFILE.xml.

How can I test a merging process on the command line?

To merge two profiles, a.xml with base.xml, run the following command:

/usr/bin/xsltproc --novalid --param replace "'false'" \
--param dontmerge1 "'package'" --param with "'a.xml'" --output out.xml \
/usr/share/autoinstall/xslt/merge.xslt base.xml

This requires sections in both profiles to be in alphabetical order (<software>, for example, needs to be listed after <add-on>). If you have created the profile with YaST, profiles are automatically sorted correctly.

The dontmerge1 parameter is optional and an example of what to do when you use the dont_merge element in your profile. See Section 5.4, “Merging of Rules and Classes” for more information.

May I call Zypper from scripts?

Zypper can only be called from AutoYaST init scripts, because during the post-script phase, YaST still has an exclusive lock on the RPM database.

If you really need to use other script types (for example a post-script) you will need to break the lock at your own risk:

<post-scripts config:type="list">
  <script>
    <filename>yast_clone.sh</filename>
    <interpreter>shell</interpreter>
    <location/>
    <feedback config:type="boolean">false</feedback>
    <source><![CDATA[#!/bin/sh
mv /var/run/zypp.pid /var/run/zypp.sav
zypper in foo
mv /var/run/zypp.sav /var/run/zypp.pid
]]></source>
  </script>
</post-scripts>
Is the order of sections in an AutoYaST profile important?

Actually the order is not important. The order of sections in the profile has no influence on the AutoYaST workflow. However, if you want to merge different profiles, sections need to be in alphabetical order.

linuxrc blocks the installation with File not signed. I need to manually interact.

Linuxrc found some unsigned file (like a driver update). To use an unsigned file, you can suppress that message by passing insecure=1 to the linuxrc parameter list (together with the autoyast=... parameter).

I want to install from DVD/USB/HD but fetch the XML file from the network.

You need to pass ifcfg to linuxrc. This is required to set up the network, otherwise AutoYaST cannot download the profile from remote. See Section C.3, “Advanced Network Setup” for more information.

Is the installation on an NFS root (/) possible?

Yes, but it is a little bit tricky. You will need to set up the environment (DHCP, TFTP, etc.) very carefully. The AutoYaST profile needs to look like the following:

<?xml version="1.0"?>
<!DOCTYPE profile>
<profile xmlns="http://www.suse.com/1.0/yast2ns" xmlns:config="http://www.suse.com/1.0/configns">
  <partitioning config:type="list">
    <drive>
      <device>/dev/nfs</device>
      <initialize config:type="boolean">false</initialize>
      <type config:type="symbol">CT_NFS</type>
      <partitions config:type="list">
        <partition>
          <filesystem config:type="symbol">nfs</filesystem>
          <fstopt>nolock</fstopt>
          <device>10.10.1.53:/tmp/m4</device>
          <mount>/</mount>
        </partition>
      </partitions>
      <use>all</use>
    </drive>
  </partitioning>
</profile>
Where can I ask questions which have not been answered here?

There is an AutoYaST mailing list where you can post your questions. Join us at http://lists.opensuse.org/opensuse-autoinstall/.

C Advanced Linuxrc Options

Linuxrc is a program used for setting up the kernel for installation purposes. It allows the user to load modules, start an installed system, a rescue system or an installation via YaST.

Linuxrc is designed to be as small as possible. Therefore, all needed programs are linked directly into one binary. So there is no need for shared libraries in the init disk.

Note
Note: Running Linuxrc on an Installed System

If you run Linuxrc on an installed system, it will work slightly differently so as not to destroy your installation. As a consequence you cannot test all features this way.

C.1 Passing parameters to Linuxrc

Unless Linuxrc is in manual mode, it will look for an info file in these locations: first /info on the flash disk and if that does not exist, for /info in the initrd. After that it parses the kernel command line for parameters. You may change the info file Linuxrc reads by setting the info command line parameter. If you do not want Linuxrc to read the kernel command line (for example because you need to specify a kernel parameter that Linuxrc recognizes as well), use linuxrc=nocmdline.

Linuxrc will always look for and parse a file /linuxrc.config. Use this file to change default values if you need to. In general, it is better to use the info file instead. Note that /linuxrc.config is read before any info file, even in manual mode.

C.2 info file format

Lines starting with # are comments, valid entries are of the form:

key: value

Note that value extends to the end of the line and therefore may contain spaces. key is matched case-insensitive.

You can use the same key-value pairs on the kernel command line using the syntax key=value. Lines that do not have the form described above are ignored.

The table below lists important keys and example values. For a complete list of linuxrc parameters refer to https://en.opensuse.org/SDB:Linuxrc.

Table C.1:
Table C.2: Advanced linuxrc keywords

Keyword: Example Value

Description

addswap: 0|3|/dev/sda5

If 0, never ask for swap; if the argument is a positive number n, activate the n'th swap partition; if the argument is a partition name, activate this swap partition.

autoyast: ftp://AUTOYASTFILE

Location of the auto installation file; activates auto installation mode. See Table 6.2, “Command Line Variables for AutoYaST” for details.

bootptimeout: 10

10 seconds timeout for BOOTP requests.

bootpwait: 5

Sleep 5 seconds between network activation and starting bootp.

display: color|mono|alt

Set the menu color scheme.

exec: COMMAND

Run command.

forceinsmod: 0|1

Use the -f option (force) when running insmod commands.

forcerootimage: 0|1

Load the installation system into RAM disk.

ifcfg: NETWORK_CONFIGURATION

Set up and start the network. See Section C.3, “Advanced Network Setup” for more information.

insmod: MODULE

Load MODULE.

install: URL

Install from the repository specified with URL. For the syntax of URL refer to https://en.opensuse.org/SDB:Linuxrc#url_descr.

keytable: de-lat1-nd

Virtual console keyboard map to load.

language: de_DE

Language preselected for the installation.

loghost: 10.10.0.22

Enable remote logging via syslog.

memloadimage: 50000

Load installation system into RAM disk if free memory is above 50000 KB.

memlimit: 10000

Ask for swap if free memory drops below 10000 KB.

memYaST: 20000

Run YaST in text mode if free memory is below 20000 KB.

memYaSTText: 10000

Ask for swap before starting YaST if free memory is below 10000 KB.

proxy: 10.10.0.1

Proxy (either FTP or HTTP).

rescue: 1|nfs://server/dir

Load the rescue system; the URL variant specifies the location of the rescue image explicitly.

rescueimage: /suse/images/rescue

Location of the rescue system image.

rootimage: /suse/images/root

Location of the installation system image.

textmode: 1

Start YaST in text mode.

usbwait: 4

Wait 4 seconds after loading the USB modules.

y2confirm

Overrides the confirm parameter in a control file and requests confirmation of installation proposal.

C.3 Advanced Network Setup

Even if parameters like hostip, nameserver, and gateway are passed to linuxrc, the network is only started when it is needed (for example, when installing via SSH or VNC). Since autoyast is not a linuxrc parameter (this parameter is ignored by linuxrc and only passed to YaST), the network will not be started automatically when specifying a remote location for the AutoYaST profile.

Therefore the network needs to be started explicitly. This used to be done with the linuxrc parameter netsetup. Starting with SUSE Linux Enterprise Server 12, the parameter ifcfg is available. It offers more configuration options, for example configuring more than one interface. ifcfg directly controls the content of the /etc/sysconfig/network/ifcfg-* files.

DHCP Network Configuration

The general syntax to configure DHCP is

 ifcfg=INTERFACE=DHCP*,OPTION1=VALUE1,OPTION2=VALUE2

where INTERFACE is the interface name, for example eth0, or eth* for all interfaces. DHCP* can either be dhcp (IPv4 and IPv6), dhcp4, or dhcp6.

To set up DHCP for eth0 use:

ifcfg=eth0=dhcp

To set up DHCP on all interfaces use:

ifcfg=eth*=dhcp
Static Network Configuration

The general syntax to configure a static network is

ifcfg=INTERFACE=IP_LIST,GATEWAY_LIST,NAMESERVER_LIST,DOMAINSEARCH_LIST,\
OPTION1=value1,...

where INTERFACE is the interface name, for example eth0. If using eth*, the first device available will be used. The other parameters need to be replaced with the respective values in the given order. Example:

ifcfg=eth0=192.168.2.100/24,192.168.5.1,192.168.1.116,example.com

When specifying multiple addresses for a parameter, use spaces to separate them and quote the complete string. The following example uses two name servers and a search list containing two domains.

ifcfg="eth0=192.168.2.100/24,192.168.5.1,192.168.1.116 192.168.1.117,example.com example.net"

For more information refer to https://en.opensuse.org/SDB:Linuxrc#Network_Configuration.

D Documentation Updates

  • Filename: ay_docupdates.xml
  • ID: app.ay.docupdates

This chapter lists content changes for this document.

This manual was updated on the following dates:

D.1 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)

Chapter 4, Configuration and Installation Options

Updated Section 4.9.2, “Installing Additional/Customized Packages or Products”.

Bugfixes

D.2 April 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP2)

Bugfixes

D.3 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)

General
  • The e-mail address for documentation feedback has changed to doc-team@suse.com.

  • The documentation for Docker has been enhanced and renamed to Docker Guide.

Section 6.3.1, “Command Line Options”

Added jing as an alternative to xmllint for control file validation (Section 3.3, “Creating/Editing a Control File Manually”).

Chapter 4, Configuration and Installation Options
Chapter 6, The Auto-Installation Process

Added a description for the linuxrc parameter autoyast2 to Section 6.3.1, “Command Line Options”.

Bugfixes

D.4 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)

General
  • SMT Guide is now part of the documentation for SUSE Linux Enterprise Server.

  • Add-ons provided by SUSE have been renamed as modules and extensions. The manuals have been updated to reflect this change.

  • Numerous small fixes and additions to the documentation, based on technical feedback.

  • The registration service has been changed from Novell Customer Center to SUSE Customer Center.

  • In YaST, you will now reach Network Settings via the System group. Network Devices is gone (https://bugzilla.suse.com/show_bug.cgi?id=867809).

Bugfixes

D.5 February 2015 (Documentation Maintenance Update)

Bugfixes

D.6 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)

General
  • Removed all KDE documentation and references because KDE is no longer shipped.

  • Removed all references to SuSEconfig, which is no longer supported (Fate #100011).

  • Move from System V init to systemd (Fate #310421). Updated affected parts of the documentation.

  • YaST Runlevel Editor has changed to Services Manager (Fate #312568). Updated affected parts of the documentation.

  • Removed all references to ISDN support, as ISDN support has been removed (Fate #314594).

  • Removed all references to the YaST DSL module as it is no longer shipped (Fate #316264).

  • Removed all references to the YaST Modem module as it is no longer shipped (Fate #316264).

  • Btrfs has become the default file system for the root partition (Fate #315901). Updated affected parts of the documentation.

  • The dmesg now provides human-readable time stamps in ctime()-like format (Fate #316056). Updated affected parts of the documentation.

  • syslog and syslog-ng have been replaced by rsyslog (Fate #316175). Updated affected parts of the documentation.

  • MariaDB is now shipped as the relational database instead of MySQL (Fate #313595). Updated affected parts of the documentation.

  • SUSE-related products are no longer available from http://download.novell.com but from http://download.suse.com. Adjusted links accordingly.

  • Novell Customer Center has been replaced with SUSE Customer Center. Updated affected parts of the documentation.

  • /var/run is mounted as tmpfs (Fate #303793). Updated affected parts of the documentation.

  • The following architectures are no longer supported: IA64 and x86. Updated affected parts of the documentation.

  • The traditional method for setting up the network with ifconfig has been replaced by wicked. Updated affected parts of the documentation.

  • A lot of networking commands are deprecated and have been replaced by newer commands (usually ip). Updated affected parts of the documentation.

    arp: ip neighbor
    ifconfig: ip addr, ip link
    iptunnel: ip tunnel
    iwconfig: iw
    nameif: ip link, ifrename
    netstat: ss, ip route, ip -s link, ip maddr
    route: ip route
  • Numerous small fixes and additions to the documentation, based on technical feedback.

Chapter 1, Introduction
Chapter 4, Configuration and Installation Options
Bugfixes
SUSE Linux Enterprise Server 12 SP3

Security Guide

Introduces basic concepts of system security, covering both local and network security aspects. Shows how to use the product inherent security software like AppArmor or the auditing system that reliably collects information about any security-relevant events.

Publication Date: April 04, 2018
About This Guide
Available Documentation
Feedback
Documentation Conventions
1 Security and Confidentiality
1.1 Local Security and Network Security
1.2 Some General Security Tips and Tricks
1.3 Using the Central Security Reporting Address
I Authentication
2 Authentication with PAM
2.1 What is PAM?
2.2 Structure of a PAM Configuration File
2.3 The PAM Configuration of sshd
2.4 Configuration of PAM Modules
2.5 Configuring PAM Using pam-config
2.6 Manually Configuring PAM
2.7 For More Information
3 Using NIS
3.1 Configuring NIS Servers
3.2 Configuring NIS Clients
4 Setting Up Authentication Servers and Clients Using YaST
4.1 Configuring an Authentication Server with YaST
4.2 Configuring an Authentication Client with YaST
4.3 SSSD
5 LDAP—A Directory Service
5.1 LDAP versus NIS
5.2 Structure of an LDAP Directory Tree
5.3 Configuring an LDAP Client with YaST
5.4 Configuring LDAP Users and Groups in YaST
5.5 Manually Configuring an LDAP Server
5.6 Manually Administering LDAP Data
5.7 For More Information
6 Network Authentication with Kerberos
6.1 Kerberos Terminology
6.2 How Kerberos Works
6.3 User View of Kerberos
6.4 Installing and Administering Kerberos
6.5 Setting up Kerberos using LDAP and Kerberos Client
6.6 For More Information
7 Active Directory Support
7.1 Integrating Linux and Active Directory Environments
7.2 Background Information for Linux Active Directory Support
7.3 Configuring a Linux Client for Active Directory
7.4 Logging In to an Active Directory Domain
7.5 Changing Passwords
II Local Security
8 Configuring Security Settings with YaST
8.1 Security Overview
8.2 Predefined Security Configurations
8.3 Password Settings
8.4 Boot Settings
8.5 Login Settings
8.6 User Addition
8.7 Miscellaneous Settings
9 Authorization with PolKit
9.1 Conceptual Overview
9.2 Authorization Types
9.3 Querying Privileges
9.4 Modifying Configuration Files
9.5 Restoring the Default Privileges
10 Access Control Lists in Linux
10.1 Traditional File Permissions
10.2 Advantages of ACLs
10.3 Definitions
10.4 Handling ACLs
10.5 ACL Support in Applications
10.6 For More Information
11 Encrypting Partitions and Files
11.1 Setting Up an Encrypted File System with YaST
11.2 Using Encrypted Home Directories
11.3 Encrypting Files with GPG
12 Certificate Store
12.1 Activating Certificate Store
12.2 Importing Certificates
13 Intrusion Detection with AIDE
13.1 Why Use AIDE?
13.2 Setting Up an AIDE Database
13.3 Local AIDE Checks
13.4 System Independent Checking
13.5 For More Information
III Network Security
14 SSH: Secure Network Operations
14.1 ssh—Secure Shell
14.2 scp—Secure Copy
14.3 sftp—Secure File Transfer
14.4 The SSH Daemon (sshd)
14.5 SSH Authentication Mechanisms
14.6 Port Forwarding
14.7 For More Information
15 Masquerading and Firewalls
15.1 Packet Filtering with iptables
15.2 Masquerading Basics
15.3 Firewalling Basics
15.4 SuSEFirewall2
15.5 For More Information
16 Configuring a VPN Server
16.1 Conceptual Overview
16.2 Setting Up a Simple Test Scenario
16.3 Setting Up Your VPN Server Using a Certificate Authority
16.4 Setting Up a VPN Server or Client Using YaST
16.5 For More Information
17 Managing X.509 Certification
17.1 The Principles of Digital Certification
17.2 YaST Modules for CA Management
IV Confining Privileges with AppArmor
18 Introducing AppArmor
18.1 AppArmor Components
18.2 Background Information on AppArmor Profiling
19 Getting Started
19.1 Installing AppArmor
19.2 Enabling and Disabling AppArmor
19.3 Choosing Applications to Profile
19.4 Building and Modifying Profiles
19.5 Updating Your Profiles
20 Immunizing Programs
20.1 Introducing the AppArmor Framework
20.2 Determining Programs to Immunize
20.3 Immunizing cron Jobs
20.4 Immunizing Network Applications
21 Profile Components and Syntax
21.1 Breaking an AppArmor Profile into Its Parts
21.2 Profile Types
21.3 Include Statements
21.4 Capability Entries (POSIX.1e)
21.5 Network Access Control
21.6 Profile Names, Flags, Paths, and Globbing
21.7 File Permission Access Modes
21.8 Execute Modes
21.9 Resource Limit Control
21.10 Auditing Rules
22 AppArmor Profile Repositories
23 Building and Managing Profiles with YaST
23.1 Manually Adding a Profile
23.2 Editing Profiles
23.3 Deleting a Profile
23.4 Managing AppArmor
24 Building Profiles from the Command Line
24.1 Checking the AppArmor Status
24.2 Building AppArmor Profiles
24.3 Adding or Creating an AppArmor Profile
24.4 Editing an AppArmor Profile
24.5 Unloading Unknown AppArmor Profiles
24.6 Deleting an AppArmor Profile
24.7 Two Methods of Profiling
24.8 Important File Names and Directories
25 Profiling Your Web Applications Using ChangeHat
25.1 Configuring Apache for mod_apparmor
25.2 Managing ChangeHat-Aware Applications
26 Confining Users with pam_apparmor
27 Managing Profiled Applications
27.1 Reacting to Security Event Rejections
27.2 Maintaining Your Security Profiles
28 Support
28.1 Updating AppArmor Online
28.2 Using the Man Pages
28.3 For More Information
28.4 Troubleshooting
28.5 Reporting Bugs for AppArmor
29 AppArmor Glossary
V SELinux
30 Configuring SELinux
30.1 Why Use SELinux?
30.2 Policy
30.3 Installing SELinux Packages and Modifying GRUB 2
30.4 SELinux Policy
30.5 Configuring SELinux
30.6 Managing SELinux
30.7 Troubleshooting
VI The Linux Audit Framework
31 Understanding Linux Audit
31.1 Introducing the Components of Linux Audit
31.2 Configuring the Audit Daemon
31.3 Controlling the Audit System Using auditctl
31.4 Passing Parameters to the Audit System
31.5 Understanding the Audit Logs and Generating Reports
31.6 Querying the Audit Daemon Logs with ausearch
31.7 Analyzing Processes with autrace
31.8 Visualizing Audit Data
31.9 Relaying Audit Event Notifications
32 Setting Up the Linux Audit Framework
32.1 Determining the Components to Audit
32.2 Configuring the Audit Daemon
32.3 Enabling Audit for System Calls
32.4 Setting Up Audit Rules
32.5 Configuring Audit Reports
32.6 Configuring Log Visualization
33 Introducing an Audit Rule Set
33.1 Adding Basic Audit Configuration Parameters
33.2 Adding Watches on Audit Log Files and Configuration Files
33.3 Monitoring File System Objects
33.4 Monitoring Security Configuration Files and Databases
33.5 Monitoring Miscellaneous System Calls
33.6 Filtering System Call Arguments
33.7 Managing Audit Event Records Using Keys
34 Useful Resources
A Achieving PCI-DSS Compliance
A.1 What is the PCI-DSS?
A.2 Focus of This Document: Areas Relevant to the Operating System
A.3 Requirements in Detail
B Documentation Updates
B.1 January 2018 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)
B.2 January 2018 (Maintenance Release for SUSE Linux Enterprise Server 12 SP3)
B.3 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)
B.4 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)
B.5 March 2016 (Maintenance Release of SUSE Linux Enterprise Server 12 SP1)
B.6 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)
B.7 February 2015 (Documentation Maintenance Update)
B.8 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)
C GNU Licenses
C.1 GNU Free Documentation License
List of Figures
3.1 NIS Server Setup
3.2 Master Server Setup
3.3 Changing the Directory and Synchronizing Files for a NIS Server
3.4 NIS Server Maps Setup
3.5 Setting Request Permissions for a NIS Server
3.6 Setting Domain and Address of a NIS Server
4.1 YaST Authentication Server Configuration
4.2 YaST LDAP Server—New Database
4.3 YaST Kerberos Authentication
4.4 YaST Editing Authentication Server Configuration
4.5 YaST Authentication Server Database Configuration
5.1 Structure of an LDAP Directory
5.2 LDAP and Kerberos Client Window
6.1 Kerberos Network Topology
6.2 LDAP and Kerberos Client Window
7.1 Schema of Winbind-based Active Directory Authentication
7.2 Main Window of User Logon Management
7.3 Enrolling into a Domain
7.4 Configuration Window of User Logon Management
7.5 Determining Windows Domain Membership
7.6 Providing Administrator Credentials
8.1 YaST Security Center and Hardening: Security Overview
10.1 Minimum ACL: ACL Entries Compared to Permission Bits
10.2 Extended ACL: ACL Entries Compared to Permission Bits
15.1 iptables: A Packet's Possible Paths
15.2 Firewall Configuration: Allowed Services
16.1 Routed VPN
16.2 Bridged VPN - Scenario 1
16.3 Bridged VPN - Scenario 2
16.4 Bridged VPN - Scenario 3
17.1 YaST CA Module—Basic Data for a Root CA
17.2 YaST CA Module—Using a CA
17.3 Certificates of a CA
17.4 YaST CA Module—Extended Settings
24.1 aa-notify Message in GNOME
25.1 Adminer Login Page
30.1 Selecting all SELinux Packages in YaST
31.1 Introducing the Components of Linux Audit
31.2 Flow Graph—Program versus System Call Relationship
31.3 Bar Chart—Common Event Types
List of Examples
2.1 PAM Configuration for sshd (/etc/pam.d/sshd)
2.2 Default Configuration for the auth Section (common-auth)
2.3 Default Configuration for the account Section (common-account)
2.4 Default Configuration for the password Section (common-password)
2.5 Default Configuration for the session Section (common-session)
2.6 pam_env.conf
5.1 Excerpt from schema.core
5.2 An LDIF File
5.3 ldapadd with example.ldif
5.4 LDIF Data for Tux
5.5 Modified LDIF File tux.ldif
16.1 VPN Server Configuration File
16.2 VPN Client Configuration File
19.1 Output of aa-unconfined
24.1 Learning Mode Exception: Controlling Access to Specific Resources
24.2 Learning Mode Exception: Defining Permissions for an Entry
30.1 Security Context Settings Using ls -Z
30.2 Verifying that SELinux is functional
30.3 Getting a List of Booleans and Verifying Policy Access
30.4 Getting File Context Information
30.5 The default context for directories in the root directory
30.6 Showing SELinux settings for processes with ps Zaux
30.7 Viewing Default File Contexts
30.8 Example Lines from /etc/audit/audit.log
30.9 Analyzing Audit Messages
30.10 Viewing Which Lines Deny Access
30.11 Creating a Policy Module Allowing an Action Previously Denied
31.1 Example output of auditctl -s
31.2 Example Audit Rules—Audit System Parameters
31.3 Example Audit Rules—File System Auditing
31.4 Example Audit Rules—System Call Auditing
31.5 Deleting Audit Rules and Events
31.6 Listing Rules with auditctl -l
31.7 A Simple Audit Event—Viewing the Audit Log
31.8 An Advanced Audit Event—Login via SSH
31.9 Example /etc/audisp/audispd.conf
31.10 Example /etc/audisp/plugins.d/syslog.conf

Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

About This Guide

  • Filename: security_intro.xml
  • ID: preface.security

This manual introduces the basic concepts of system security on SUSE Linux Enterprise Server. It covers extensive documentation about the authentication mechanisms available on Linux, such as NIS or LDAP. It deals with aspects of local security like access control lists, encryption and intrusion detection. In the network security part you learn how to secure computers with firewalls and masquerading, and how to set up virtual private networks (VPN). This manual shows how to use security software like AppArmor (which lets you specify per program which files the program may read, write, and execute) or the auditing system that collects information about security-relevant events.

1 Available Documentation

  • Filename: common_intro_available_doc_i.xml
  • ID: no ID found
Note
Note: Online Documentation and Latest Updates

Documentation for our products is available at http://www.suse.com/documentation/, where you can also find the latest updates, and browse or download the documentation in various formats.

In addition, the product documentation is usually available in your installed system under /usr/share/doc/manual.

The following documentation is available for this product:

Installation Quick Start

Lists the system requirements and guides you step-by-step through the installation of SUSE Linux Enterprise Server from DVD, or from an ISO image.

Deployment Guide

Shows how to install single or multiple systems and how to exploit the product inherent capabilities for a deployment infrastructure. Choose from various approaches, ranging from a local installation or a network installation server to a mass deployment using a remote-controlled, highly-customized, and automated installation technique.

Administration Guide

Covers system administration tasks like maintaining, monitoring and customizing an initially installed system.

Virtualization Guide

Describes virtualization technology in general, and introduces libvirt—the unified interface to virtualization—and detailed information on specific hypervisors.

Storage Administration Guide

Provides information about how to manage storage devices on a SUSE Linux Enterprise Server.

AutoYaST

AutoYaST is a system for unattended mass deployment SUSE Linux Enterprise Server systems using an AutoYaST profile containing installation and configuration data. The manual guides you through the basic steps of auto-installation: preparation, installation, and configuration.

Security Guide

Introduces basic concepts of system security, covering both local and network security aspects. Shows how to use the product inherent security software like AppArmor or the auditing system that reliably collects information about any security-relevant events.

Security and Hardening Guide

Deals with the particulars of installing and setting up a secure SUSE Linux Enterprise Server, and additional post-installation processes required to further secure and harden that installation. Supports the administrator with security-related choices and decisions.

System Analysis and Tuning Guide

An administrator's guide for problem detection, resolution and optimization. Find how to inspect and optimize your system by means of monitoring tools and how to efficiently manage resources. Also contains an overview of common problems and solutions and of additional help and documentation resources.

SMT Guide

An administrator's guide to Subscription Management Tool—a proxy system for SUSE Customer Center with repository and registration targets. Learn how to install and configure a local SMT server, mirror and manage repositories, manage client machines, and configure clients to use SMT.

GNOME User Guide

Introduces the GNOME desktop of SUSE Linux Enterprise Server. It guides you through using and configuring the desktop and helps you perform key tasks. It is intended mainly for end users who want to make efficient use of GNOME as their default desktop.

2 Feedback

  • Filename: common_intro_feedback_i.xml
  • ID: no ID found

Several feedback channels are available:

Bugs and Enhancement Requests

For services and support options available for your product, refer to http://www.suse.com/support/.

Help for openSUSE is provided by the community. Refer to https://en.opensuse.org/Portal:Support for more information.

To report bugs for a product component, go to https://scc.suse.com/support/requests, log in, and click Create New.

User Comments

We want to hear your comments about and suggestions for this manual and the other documentation included with this product. Use the User Comments feature at the bottom of each page in the online documentation or go to http://www.suse.com/documentation/feedback.html and enter your comments there.

Mail

For feedback on the documentation of this product, you can also send a mail to doc-team@suse.com. Make sure to include the document title, the product version and the publication date of the documentation. To report errors or suggest enhancements, provide a concise description of the problem and refer to the respective section number and page (or URL).

3 Documentation Conventions

  • Filename: common_intro_typografie_i.xml
  • ID: no ID found

The following notices and typographical conventions are used in this documentation:

  • /etc/passwd: directory names and file names

  • PLACEHOLDER: replace PLACEHOLDER with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • package name : name of a package

  • Alt, AltF1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File › Save As: menu items, buttons

  • x86_64 This paragraph is only relevant for the AMD64/Intel 64 architecture. The arrows mark the beginning and the end of the text block.

    System z, POWER This paragraph is only relevant for the architectures z Systems and POWER. The arrows mark the beginning and the end of the text block.

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

  • Commands that must be run with root privileges. Often you can also prefix these commands with the sudo command to run them as non-privileged user.

    root # command
    tux > sudo command
  • Commands that can be run by non-privileged users.

    tux > command
  • Notices

    Warning
    Warning: Warning Notice

    Vital information you must be aware of before proceeding. Warns you about security issues, potential loss of data, damage to hardware, or physical hazards.

    Important
    Important: Important Notice

    Important information you should be aware of before proceeding.

    Note
    Note: Note Notice

    Additional information, for example about differences in software versions.

    Tip
    Tip: Tip Notice

    Helpful information, like a guideline or a piece of practical advice.

1 Security and Confidentiality

  • Filename: security_preface.xml
  • ID: cha.security

One of the main characteristics of a Linux or Unix system is its ability to handle several users at the same time (multiuser) and to allow these users to perform several tasks (multitasking) on the same computer simultaneously. Moreover, the operating system is network transparent. The users often do not know whether the data and applications they are using are provided locally from their machine or made available over the network.

With the multiuser capability, the data of different users must be stored separately, and security and privacy need to be guaranteed. Data security was already an important issue, even before computers could be linked through networks. Like today, the most important concern was the ability to keep data available in spite of a lost or otherwise damaged data medium (usually a hard disk).

This section is primarily focused on confidentiality issues and on ways to protect the privacy of users. But it cannot be stressed enough that a comprehensive security concept should always include procedures to have a regularly updated, workable, and tested backup in place. Without this, you could have a very hard time getting your data back—not only in the case of some hardware defect, but also in the case that someone has gained unauthorized access and tampered with files.

1.1 Local Security and Network Security

There are several ways of accessing data:

  • personal communication with people who have the desired information or access to the data on a computer

  • directly through physical access from the console of a computer

  • over a serial line

  • using a network link

In all these cases, a user should be authenticated before accessing the resources or data in question. A Web server might be less restrictive in this respect, but you still would not want it to disclose your personal data to an anonymous user.

In the list above, the first case is the one where the highest amount of human interaction is involved (such as when you are contacting a bank employee and are required to prove that you are the person owning that bank account). Then, you are asked to provide a signature, a PIN, or a password to prove that you are the person you claim to be. In some cases, it might be possible to elicit some intelligence from an informed person by mentioning known bits and pieces to win the confidence of that person. The victim could be led to reveal gradually more information, maybe without even being aware of it. Among hackers, this is called social engineering. You can only guard against this by educating people and by dealing with language and information in a conscious way. Before breaking into computer systems, attackers often try to target receptionists, service people working with the company, or even family members. Often such an attack based on social engineering is only discovered at a much later time.

A person wanting to obtain unauthorized access to your data could also use the traditional way and try to get at your hardware directly. Therefore, the machine should be protected against any tampering so that no one can remove, replace, or cripple its components. This also applies to backups and even any network cables or power cords. Also secure the boot procedure, because there are some well-known key combinations that might provoke unusual behavior. Protect yourself against this by setting passwords for the BIOS and the boot loader.

Serial terminals connected to serial ports are still used in many places. Unlike network interfaces, they do not rely on network protocols to communicate with the host. A simple cable or an infrared port is used to send plain characters back and forth between the devices. The cable itself is the weakest point of such a system: with an older printer connected to it, it is easy to record any data being transferred that way. What can be achieved with a printer can also be accomplished in other ways, depending on the effort that goes into the attack.

Reading a file locally on a host requires additional access rules than opening a network connection with a server on a different host. There is a distinction between local security and network security. The line is drawn where data must be put into packets to be sent somewhere else.

1.1.1 Local Security

Local security starts with the physical environment at the location in which computer is running. Set up your machine in a place where security is in line with your expectations and needs. The main goal of local security is to keep users separate from each other, so no user can assume the permissions or the identity of another. This is a general rule to be observed, but it is especially true for the user root, who holds system administration privileges. root can take on the identity of any other local user and read any locally-stored file without being prompted for the password.

1.1.1.1 Passwords

On a Linux system, passwords are not stored as plain text and the entered text string is not simply matched with the saved pattern. If this were the case, all accounts on your system would be compromised when someone got access to the corresponding file. Instead, the stored password is encrypted and, each time it is entered, is encrypted again and the two encrypted strings are compared. This only provides more security if the encrypted password cannot be reverse-computed into the original text string.

This is achieved by a special kind of algorithm, also called trapdoor algorithm, because it only works in one direction. An attacker who has obtained the encrypted string is not able to get your password by simply applying the same algorithm again. Instead, it would be necessary to test all the possible character combinations until a combination is found that looks like your password when encrypted. With passwords eight characters long, there are many combinations to calculate.

In the seventies, it was argued that this method would be more secure than others because of the relative slowness of the algorithm used which took a few seconds to encrypt one password. In the meantime, PCs have become powerful enough to do several hundred thousand or even millions of encryptions per second. Because of this, encrypted passwords should not be visible to regular users (/etc/shadow cannot be read by normal users). It is even more important that passwords are not easy to guess, in case the password file becomes visible because of an error. Consequently, it is not really useful to translate a password like tantalize into t@nt@1lz3.

Replacing some letters of a word with similar looking numbers (like writing the password tantalize as t@nt@1lz3) is not sufficient. Password cracking programs that use dictionaries to guess words also play with substitutions like that. A better way is to make up a word that only makes sense to you personally, like the first letters of the words of a sentence or the title of a book, such as The Name of the Rose by Umberto Eco. This would give the following safe password: TNotRbUE9. In contrast, passwords like beerbuddy or jasmine76 are easily guessed even by someone who has only some casual knowledge about you.

1.1.1.2 The Boot Procedure

Configure your system so it cannot be booted from a removable device, either by removing the drives entirely or by setting a BIOS password and configuring the BIOS to allow booting from a hard disk only. Normally, a Linux system is started by a boot loader, allowing you to pass additional options to the booted kernel. Prevent others from using such parameters during boot by setting an additional password for the boot loader (see Section 12.2.6, “Setting a Boot Password” for instructions). This is crucial to your system's security. Not only does the kernel itself run with root permissions, but it is also the first authority to grant root permissions at system start-up.

1.1.1.3 File Permissions

As a general rule, always work with the most restrictive privileges possible for a given task. For example, it is definitely not necessary to be root to read or write e-mail. If the mail program has a bug, this bug could be exploited for an attack that acts with exactly the permissions of the program when it was started. By following the above rule, minimize the possible damage.

The permissions of all files included in the SUSE Linux Enterprise Server distribution are carefully chosen. A system administrator who installs additional software or other files should take great care when doing so, especially when setting the permission bits. Experienced and security-conscious system administrators always use the -l option with the command ls to get an extensive file list, which allows them to detect any incorrect file permissions immediately. An incorrect file attribute does not only mean that files could be changed or deleted. These modified files could be executed by root or, in the case of configuration files, programs could use such files with the permissions of root. This significantly increases the possibilities of an attack. Attacks like these are called cuckoo eggs, because the program (the egg) is executed (hatched) by a different user (bird), similar to how a cuckoo tricks other birds into hatching its eggs.

An SUSE® Linux Enterprise Server system includes the files permissions, permissions.easy, permissions.secure, and permissions.paranoid, all in the directory /etc. The purpose of these files is to define special permissions, such as world-writable directories or, for files, the setuser ID bit (programs with the setuser ID bit set do not run with the permissions of the user that has launched it, but with the permissions of the file owner, usually root). An administrator can use the file /etc/permissions.local to add his own settings.

To define which of the above files is used by SUSE Linux Enterprise Server's configuration programs to set permissions, select Local Security in the Security and Users section of YaST. To learn more about the topic, read the comments in /etc/permissions or consult the manual page of chmod (man chmod).

1.1.1.4 Buffer Overflows and Format String Bugs

Special care must be taken whenever a program needs to process data that could be changed by a user, but this is more of an issue for the programmer of an application than for regular users. The programmer must make sure that his application interprets data in the correct way, without writing it into memory areas that are too small to hold it. Also, the program should hand over data in a consistent manner, using interfaces defined for that purpose.

A buffer overflow can happen if the actual size of a memory buffer is not taken into account when writing to that buffer. There are cases where this data (as generated by the user) uses up more space than what is available in the buffer. As a result, data is written beyond the end of that buffer area, which, under certain circumstances, makes it possible for a program to execute program sequences influenced by the user (and not by the programmer), rather than processing user data only. A bug of this kind may have serious consequences, especially if the program is being executed with special privileges (see Section 1.1.1.3, “File Permissions”).

Format string bugs work in a slightly different way, but again it is the user input that could lead the program astray. Usually, these programming errors are exploited with programs executed with special permissions—setuid and setgid programs—which also means that you can protect your data and your system from such bugs by removing the corresponding execution privileges from programs. Again, the best way is to apply a policy of using the lowest possible privileges (see Section 1.1.1.3, “File Permissions”).

Given that buffer overflows and format string bugs are related to the handling of user data, they are only exploitable if access has been given to a local account. Many of the bugs that have been reported can also be exploited over a network link. Accordingly, buffer overflows and format string bugs should be classified as being relevant for both local and network security.

1.1.1.5 Viruses

Contrary to popular opinion, there are viruses that run on Linux. However, the viruses that are known were released by their authors as a proof of concept that the technique works as intended. None of these viruses have been spotted in the wild so far.

Viruses cannot survive and spread without a host on which to live. In this case, the host would be a program or an important storage area of the system (for example, the master boot record) that needs to be writable for the program code of the virus. Because of its multiuser capability, Linux can restrict write access to certain files (this is especially important with system files). Therefore, if you did your normal work with root permissions, you would increase the chance of the system being infected by a virus. In contrast, if you follow the principle of using the lowest possible privileges as mentioned above, chances of getting a virus are slim.

Apart from that, you should never rush into executing a program from some Internet site that you do not really know. SUSE Linux Enterprise Server's RPM packages carry a cryptographic signature, as a digital label that the necessary care was taken to build them. Viruses are a typical sign that the administrator or the user lacks the required security awareness, putting at risk even a system that should be highly secure by its very design.

Viruses should not be confused with worms, which belong entirely to the world of networks. Worms do not need a host to spread.

1.1.2 Network Security

Network security is important for protecting from an attack that is started outside the network. The typical login procedure requiring a user name and a password for user authentication is still a local security issue. In the particular case of logging in over a network, differentiate between the two security aspects. What happens until the actual authentication is network security and anything that happens afterward is local security.

1.1.2.1 X Window System and X Authentication

As mentioned at the beginning, network transparency is one of the central characteristics of a Unix system. X, the windowing system of Unix operating systems, can use this feature in an impressive way. With X, it is no problem to log in to a remote host and start a graphical program that is then sent over the network to be displayed on your computer.

When an X client needs to be displayed remotely using an X server, the latter should protect the resource managed by it (the display) from unauthorized access. In more concrete terms, certain permissions must be given to the client program. With the X Window System, there are two ways to do this, called host-based access control and cookie-based access control. The former relies on the IP address of the host where the client should run. The program to control this is xhost. xhost enters the IP address of a legitimate client into a database belonging to the X server. However, relying on IP addresses for authentication is not very secure. For example, if there were a second user working on the host sending the client program, that user would have access to the X server as well—like someone stealing the IP address. Because of these shortcomings, this authentication method is not described in more detail here, but you can learn about it with man xhost.

In the case of cookie-based access control, a character string is generated that is only known to the X server and to the legitimate user, like an ID card of some kind. This cookie is stored on login in the file .Xauthority in the user's home directory and is available to any X client wanting to use the X server to display a window. The file .Xauthority can be examined by the user with the tool xauth. If you rename .Xauthority, or if you delete the file from your home directory by accident, you would not be able to open any new windows or X clients.

SSH (secure shell) can be used to encrypt a network connection and forward it to an X server transparently. This is also called X forwarding. X forwarding is achieved by simulating an X server on the server side and setting a DISPLAY variable for the shell on the remote host. Further details about SSH can be found in Chapter 14, SSH: Secure Network Operations.

Warning
Warning: X Forwarding Can Be Insecure

If you do not consider the host where you log in to be a secure host, do not use X forwarding. If X forwarding is enabled, an attacker could authenticate via your SSH connection. The attacker could then intrude on your X server and, for example, read your keyboard input.

1.1.2.2 Buffer Overflows and Format String Bugs

As discussed in Section 1.1.1.4, “Buffer Overflows and Format String Bugs”, buffer overflows and format string bugs should be classified as issues applying to both local and network security. As with the local variants of such bugs, buffer overflows in network programs, when successfully exploited, are mostly used to obtain root permissions. Even if that is not the case, an attacker could use the bug to gain access to an unprivileged local account to exploit other vulnerabilities that might exist on the system.

Buffer overflows and format string bugs exploitable over a network link are certainly the most frequent form of remote attacks, in general. Exploits for these—programs to exploit these newly-found security holes—are often posted on security mailing lists. They can be used to target the vulnerability without knowing the details of the code.

Experience has shown that the availability of exploit codes has contributed to more secure operating systems, as they force operating system makers to fix problems in their software. With free software, anyone has access to the source code (SUSE Linux Enterprise Server comes with complete source code) and anyone who finds a vulnerability and its exploit code can submit a patch to fix the corresponding bug.

1.1.2.3 Denial of Service

The purpose of a denial of service (DoS) attack is to block a server program or even an entire system. This can be achieved in several ways: overloading the server, keeping it busy with garbage packets, or exploiting a remote buffer overflow. Often, a DoS attack is made with the sole purpose of making the service disappear. However, when a given service has become unavailable, communications could become vulnerable to man-in-the-middle attacks (sniffing, TCP connection hijacking, spoofing) and DNS poisoning.

1.1.2.4 Man in the Middle: Sniffing, Hijacking, Spoofing

In general, any remote attack performed by an attacker who puts himself between the communicating hosts is called a man-in-the-middle attack. What almost all types of man-in-the-middle attacks have in common is that the victim is usually not aware that there is something happening. There are many variants. For example, the attacker could pick up a connection request and forward that to the target machine. Now the victim has unwittingly established a connection with the wrong host, because the other end is posing as the legitimate destination machine.

The simplest form of a man-in-the-middle attack is called sniffer (the attacker is only listening to the network traffic passing by). As a more complex attack, the man in the middle could try to take over an already established connection (hijacking). To do so, the attacker would need to analyze the packets for some time to be able to predict the TCP sequence numbers belonging to the connection. When the attacker finally seizes the role of the target host, the victims notice this, because they get an error message saying the connection was terminated because of a failure. That there are protocols not secured against hijacking through encryption (which only perform a simple authentication procedure upon establishing the connection) makes it easier for attackers.

Spoofing is an attack where packets are modified to contain counterfeit source data, usually the IP address. Most active forms of attack rely on sending out such fake packets (something that, on a Linux machine, can only be done by the superuser (root)).

Many of the attacks mentioned are carried out in combination with a DoS. If an attacker sees an opportunity to bring down a certain host abruptly, even if only for a short time, it makes it easier for him to push the active attack, because the host cannot interfere with the attack for some time.

1.1.2.5 DNS Poisoning

DNS poisoning means that the attacker corrupts the cache of a DNS server by replying to it with spoofed DNS reply packets, trying to get the server to send certain data to a victim who is requesting information from that server. Many servers maintain a trust relationship with other hosts, based on IP addresses or host names. The attacker needs a good understanding of the actual structure of the trust relationships among hosts to disguise itself as one of the trusted hosts. Usually, the attacker analyzes some packets received from the server to get the necessary information. The attacker often needs to target a well-timed DoS attack at the name server as well. Protect yourself by using encrypted connections that can verify the identity of the hosts to which to connect.

1.1.2.6 Worms

Worms are often confused with viruses, but there is a clear difference between the two. Unlike viruses, worms do not need to infect a host program to live. Instead, they are specialized to spread as quickly as possible on network structures. The worms that appeared in the past, such as Ramen, Lion, or Adore, used well-known security holes in server programs like bind8. Protection against worms is relatively easy. Given that some time elapses between the discovery of a security hole and the moment the worm hits your server, there is a good chance that an updated version of the affected program is available on time. That is only useful if the administrator actually installs the security updates on the systems in question.

1.2 Some General Security Tips and Tricks

To handle security competently, it is important to observe some recommendations. You may find the following list of rules useful in dealing with basic security concerns:

  • Get and install the updated packages recommended by security announcements as quickly as possible.

  • Stay informed about the latest security issues:

  • Discuss any security issues of interest on our mailing list opensuse-security@opensuse.org.

  • According to the rule of using the most restrictive set of permissions possible for every job, avoid doing your regular jobs as root. This reduces the risk of getting a cuckoo egg or a virus and protects you from your own mistakes.

  • If possible, always try to use encrypted connections to work on a remote machine. Using ssh (secure shell) to replace telnet, ftp, rsh, and rlogin should be standard practice.

  • Avoid using authentication methods based solely on IP addresses.

  • Try to keep the most important network-related packages up-to-date and subscribe to the corresponding mailing lists to receive announcements on new versions of such programs (bind, postfix, ssh, etc.). The same should apply to software relevant to local security.

  • Change the /etc/permissions file to optimize the permissions of files crucial to your system's security. If you remove the setuid bit from a program, it might well be that it cannot do its job anymore in the intended way. On the other hand, the program will usually have ceased to be a potential security risk. You might take a similar approach with world-writable directories and files.

  • Disable any network services you do not absolutely require for your server to work properly. This makes your system safer. Open ports, with the socket state LISTEN, can be found with the program netstat. As for the options, it is recommended to use netstat -ap or netstat -anp. The -p option allows you to see which process is occupying a port under which name.

    Compare the netstat results with those of a thorough port scan done from outside your host. An excellent program for this job is nmap, which not only checks out the ports of your machine, but also draws some conclusions as to which services are waiting behind them. However, port scanning may be interpreted as an aggressive act, so do not do this on a host without the explicit approval of the administrator. Finally, remember that it is important not only to scan TCP ports, but also UDP ports (options -sS and -sU).

  • To monitor the integrity of the files of your system in a reliable way, use the program AIDE (Advanced Intrusion Detection Environment), available on SUSE Linux Enterprise Server. Encrypt the database created by AIDE to prevent someone from tampering with it. Furthermore, keep a backup of this database available outside your machine, stored on an external data medium not connected to it by a network link.

  • Take proper care when installing any third-party software. There have been cases where a hacker had built a Trojan horse into the TAR archive of a security software package, which was fortunately discovered very quickly. If you install a binary package, have no doubts about the site from which you downloaded it.

    SUSE's RPM packages are gpg-signed. The key used by SUSE for signing is:

    ID:9C800ACA 2000-10-19 SUSE Package Signing Key <build@suse.de>
         Key fingerprint = 79C1 79B2 E1C8 20C1 890F 9994 A84E DAE8 9C80 0ACA

    The command rpm --checksig package.rpm shows whether the checksum and the signature of an uninstalled package are correct. Find the key on the first CD of the distribution and on most key servers worldwide.

  • Check backups of user and system files regularly. Consider that if you do not test whether the backup works, it might actually be worthless.

  • Check your log files. Whenever possible, write a small script to search for suspicious entries. Admittedly, this is not exactly a trivial task. In the end, only you can know which entries are unusual and which are not.

  • Use tcp_wrapper to restrict access to the individual services running on your machine, so you have explicit control over which IP addresses can connect to a service. For further information regarding tcp_wrapper, consult the manual pages of tcpd and hosts_access (man 8 tcpd, man hosts_access).

  • Use SuSEfirewall to enhance the security provided by tcpd (tcp_wrapper).

  • Design your security measures to be redundant: a message seen twice is much better than no message.

  • If you use suspend to disk, consider configuring the suspend image encryption using the configure-suspend-encryption.sh script. The program creates the key, copies it to /etc/suspend.key, and modifies /etc/suspend.conf to use encryption for suspend images.

1.3 Using the Central Security Reporting Address

If you discover a security-related problem (check the available update packages first), write an e-mail to <>. Include a detailed description of the problem and the version number of the package concerned. SUSE will try to send a reply when possible. You are encouraged to pgp-encrypt your e-mail messages. SUSE's PGP key is:

ID:3D25D3D9 1999-03-06 SUSE Security Team <security@suse.de>
Key fingerprint = 73 5F 2E 99 DF DB 94 C4 8F 5A A3 AE AF 22 F2 D5

This key is also available for download from http://www.suse.com/support/security/contact.html.

Part I Authentication

2 Authentication with PAM

Linux uses PAM (pluggable authentication modules) in the authentication process as a layer that mediates between user and application. PAM modules are available on a systemwide basis, so they can be requested by any application. This chapter describes how the modular authentication mechanism works and how it is configured.

3 Using NIS

When multiple Unix systems in a network access common resources, it becomes imperative that all user and group identities are the same for all machines in that network. The network should be transparent to users: their environments should not vary, regardless of which machine they are actually using. This can be done by means of NIS and NFS services. NFS distributes file systems over a network and is discussed in Chapter 27, Sharing File Systems with NFS.

NIS (Network Information Service) can be described as a database-like service that provides access to the contents of /etc/passwd, /etc/shadow, and /etc/group across networks. NIS can also be used for other purposes (making the contents of files like /etc/hosts or /etc/services available, for example), but this is beyond the scope of this introduction. People often refer to NIS as YP, because it works like the network's yellow pages.

4 Setting Up Authentication Servers and Clients Using YaST

The Authentication Server is based on LDAP and optionally Kerberos. On SUSE Linux Enterprise Server you can configure it with a YaST wizard.

For more information about LDAP, see Chapter 5, LDAP—A Directory Service, and about Kerberos, see Chapter 6, Network Authentication with Kerberos.

5 LDAP—A Directory Service

The Lightweight Directory Access Protocol (LDAP) is a set of protocols designed to access and maintain information directories. LDAP can be used for user and group management, system configuration management, address management, and more. This chapter provides a basic understanding of how OpenLDAP works.

6 Network Authentication with Kerberos

An open network provides no means of ensuring that a workstation can identify its users properly, except through the usual password mechanisms. In common installations, the user must enter the password each time a service inside the network is accessed. Kerberos provides an authentication method wit…

7 Active Directory Support

Active Directory* (AD) is a directory-service based on LDAP, Kerberos, and other services. It is used by Microsoft* Windows* to manage resources, services, and people. In a Microsoft Windows network, Active Directory provides information about these objects, restricts access to them, and enforces po…

2 Authentication with PAM

  • Filename: security_pam.xml
  • ID: cha.pam
Abstract

Linux uses PAM (pluggable authentication modules) in the authentication process as a layer that mediates between user and application. PAM modules are available on a systemwide basis, so they can be requested by any application. This chapter describes how the modular authentication mechanism works and how it is configured.

2.1 What is PAM?

System administrators and programmers often want to restrict access to certain parts of the system or to limit the use of certain functions of an application. Without PAM, applications must be adapted every time a new authentication mechanism, such as LDAP, Samba, or Kerberos, is introduced. However, this process is time-consuming and error-prone. One way to avoid these drawbacks is to separate applications from the authentication mechanism and delegate authentication to centrally managed modules. Whenever a newly required authentication scheme is needed, it is sufficient to adapt or write a suitable PAM module for use by the program in question.

The PAM concept consists of:

  • PAM modules, which are a set of shared libraries for a specific authentication mechanism.

  • A module stack with of one or more PAM modules.

  • A PAM-aware service which needs authentication by using a module stack or PAM modules. Usually a service is a familiar name of the corresponding application, like login or su. The service name other is a reserved word for default rules.

  • Module arguments, with which the execution of a single PAM module can be influenced.

  • A mechanism evaluating each result of a single PAM module execution. A positive value executes the next PAM module. The way a negative value is dealt with depends on the configuration: no influence, proceed up to terminate immediately and anything in between are valid options.

2.2 Structure of a PAM Configuration File

PAM can be configured in two ways:

File based configuration (/etc/pam.conf)

The configuration of each service is stored in /etc/pam.conf. However, for maintenance and usability reasons, this configuration scheme is not used in SUSE Linux Enterprise Server.

Directory based configuration (/etc/pam.d/)

Every service (or program) that relies on the PAM mechanism has its own configuration file in the /etc/pam.d/ directory. For example, the service for sshd can be found in the /etc/pam.d/sshd file.

The files under /etc/pam.d/ define the PAM modules used for authentication. Each file consists of lines, which define a service, and each line consists of a maximum of four components:

TYPE  CONTROL
 MODULE_PATH  MODULE_ARGS

The components have the following meaning:

TYPE

Declares the type of the service. PAM modules are processed as stacks. Different types of modules have different purposes. For example, one module checks the password, another verifies the location from which the system is accessed, and yet another reads user-specific settings. PAM knows about four different types of modules:

auth

Check the user's authenticity, traditionally by querying a password. However, this can also be achieved with a chip card or through biometrics (for example, fingerprints or iris scan).

account

Modules of this type check if the user has general permission to use the requested service. As an example, such a check should be performed to ensure that no one can log in with the user name of an expired account.

password

The purpose of this type of module is to enable the change of an authentication token. Usually this is a password.

session

Modules of this type are responsible for managing and configuring user sessions. They are started before and after authentication to log login attempts and configure the user's specific environment (mail accounts, home directory, system limits, etc.).

CONTROL

Indicates the behavior of a PAM module. Each module can have the following control flags:

required

A module with this flag must be successfully processed before the authentication may proceed. After the failure of a module with the required flag, all other modules with the same flag are processed before the user receives a message about the failure of the authentication attempt.

requisite

Modules having this flag must also be processed successfully, in much the same way as a module with the required flag. However, in case of failure a module with this flag gives immediate feedback to the user and no further modules are processed. In case of success, other modules are subsequently processed, like any modules with the required flag. The requisite flag can be used as a basic filter checking for the existence of certain conditions that are essential for a correct authentication.

sufficient

After a module with this flag has been successfully processed, the requesting application receives an immediate message about the success and no further modules are processed, provided there was no preceding failure of a module with the required flag. The failure of a module with the sufficient flag has no direct consequences, in the sense that any subsequent modules are processed in their respective order.

optional

The failure or success of a module with this flag does not have any direct consequences. This can be useful for modules that are only intended to display a message (for example, to tell the user that mail has arrived) without taking any further action.

include

If this flag is given, the file specified as argument is inserted at this place.

MODULE_PATH

Contains a full file name of a PAM module. It does not need to be specified explicitly, as long as the module is located in the default directory /lib/security (for all 64-bit platforms supported by SUSE® Linux Enterprise Server, the directory is /lib64/security).

MODULE_ARGS

Contains a space-separated list of options to influence the behavior of a PAM module, such as debug (enables debugging) or nullok (allows the use of empty passwords).

In addition, there are global configuration files for PAM modules under /etc/security, which define the exact behavior of these modules (examples include pam_env.conf and time.conf). Every application that uses a PAM module actually calls a set of PAM functions, which then process the information in the various configuration files and return the result to the requesting application.

To simplify the creation and maintenance of PAM modules, common default configuration files for the types auth, account, password, and session modules have been introduced. These are retrieved from every application's PAM configuration. Updates to the global PAM configuration modules in common-* are thus propagated across all PAM configuration files without requiring the administrator to update every single PAM configuration file.

The global PAM configuration files are maintained using the pam-config tool. This tool automatically adds new modules to the configuration, changes the configuration of existing ones or deletes modules (or options) from the configurations. Manual intervention in maintaining PAM configurations is minimized or no longer required.

Note
Note: 64-Bit and 32-Bit Mixed Installations

When using a 64-bit operating system, it is possible to also include a runtime environment for 32-bit applications. In this case, make sure that you also install the 32-bit version of the PAM modules.

2.3 The PAM Configuration of sshd

Consider the PAM configuration of sshd as an example:

Example 2.1: PAM Configuration for sshd (/etc/pam.d/sshd)
#%PAM-1.0 1
auth     requisite      pam_nologin.so                              2
auth     include        common-auth                                 3
account  requisite      pam_nologin.so                              2
account  include        common-account                              3
password include        common-password                             3
session  required       pam_loginuid.so                             4
session  include        common-session                              3
session  optional       pam_lastlog.so   silent noupdate showfailed 5

1

Declares the version of this configuration file for PAM 1.0. This is merely a convention, but could be used in the future to check the version.

2

Checks, if /etc/nologin exists. If it does, no user other than root may log in.

3

Refers to the configuration files of four module types: common-auth, common-account, common-password, and common-session. These four files hold the default configuration for each module type.

4

Sets the login uid process attribute for the process that was authenticated.

5

Displays information about the last login of a user.

By including the configuration files instead of adding each module separately to the respective PAM configuration, you automatically get an updated PAM configuration when an administrator changes the defaults. Formerly, you needed to adjust all configuration files manually for all applications when changes to PAM occurred or a new application was installed. Now the PAM configuration is made with central configuration files and all changes are automatically inherited by the PAM configuration of each service.

The first include file (common-auth) calls three modules of the auth type: pam_env.so, pam_gnome_keyring.so and pam_unix.so. See Example 2.2, “Default Configuration for the auth Section (common-auth)”.

Example 2.2: Default Configuration for the auth Section (common-auth)
auth  required  pam_env.so                   1
auth  optional  pam_gnome_keyring.so         2
auth  required  pam_unix.so  try_first_pass 3

1

pam_env.so loads /etc/security/pam_env.conf to set the environment variables as specified in this file. It can be used to set the DISPLAY variable to the correct value, because the pam_env module knows about the location from which the login is taking place.

2

pam_gnome_keyring.so checks the user's login and password against the GNOME key ring

3

pam_unix checks the user's login and password against /etc/passwd and /etc/shadow.

The whole stack of auth modules is processed before sshd gets any feedback about whether the login has succeeded. All modules of the stack having the required control flag must be processed successfully before sshd receives a message about the positive result. If one of the modules is not successful, the entire module stack is still processed and only then is sshd notified about the negative result.

When all modules of the auth type have been successfully processed, another include statement is processed, in this case, that in Example 2.3, “Default Configuration for the account Section (common-account)”. common-account contains only one module, pam_unix. If pam_unix returns the result that the user exists, sshd receives a message announcing this success and the next stack of modules (password) is processed, shown in Example 2.4, “Default Configuration for the password Section (common-password)”.

Example 2.3: Default Configuration for the account Section (common-account)
account  required  pam_unix.so  try_first_pass
Example 2.4: Default Configuration for the password Section (common-password)
password  requisite  pam_cracklib.so
password  optional   pam_gnome_keyring.so  use_authtok
password  required   pam_unix.so  use_authtok nullok shadow try_first_pass

Again, the PAM configuration of sshd involves only an include statement referring to the default configuration for password modules located in common-password. These modules must successfully be completed (control flags requisite and required) whenever the application requests the change of an authentication token.

Changing a password or another authentication token requires a security check. This is achieved with the pam_cracklib module. The pam_unix module used afterward carries over any old and new passwords from pam_cracklib, so the user does not need to authenticate again after changing the password. This procedure makes it impossible to circumvent the checks carried out by pam_cracklib. Whenever the account or the auth type are configured to complain about expired passwords, the password modules should also be used.

Example 2.5: Default Configuration for the session Section (common-session)
session  required  pam_limits.so
session  required  pam_unix.so  try_first_pass
session  optional  pam_umask.so
session  optional  pam_systemd.so
session  optional  pam_gnome_keyring.so auto_start only_if=gdm,gdm-password,lxdm,lightdm
session  optional  pam_env.so

As the final step, the modules of the session type (bundled in the common-session file) are called to configure the session according to the settings for the user in question. The pam_limits module loads the file /etc/security/limits.conf, which may define limits on the use of certain system resources. The pam_unix module is processed again. The pam_umask module can be used to set the file mode creation mask. Since this module carries the optional flag, a failure of this module would not affect the successful completion of the entire session module stack. The session modules are called a second time when the user logs out.

2.4 Configuration of PAM Modules

Some PAM modules are configurable. The configuration files are located in /etc/security. This section briefly describes the configuration files relevant to the sshd example—pam_env.conf and limits.conf.

2.4.1 pam_env.conf

pam_env.conf can be used to define a standardized environment for users that is set whenever the pam_env module is called. With it, preset environment variables using the following syntax:

VARIABLE  [DEFAULT=VALUE]  [OVERRIDE=VALUE]
VARIABLE

Name of the environment variable to set.

[DEFAULT=<value>]

Default VALUE the administrator wants to set.

[OVERRIDE=<value>]

Values that may be queried and set by pam_env, overriding the default value.

A typical example of how pam_env can be used is the adaptation of the DISPLAY variable, which is changed whenever a remote login takes place. This is shown in Example 2.6, “pam_env.conf”.

Example 2.6: pam_env.conf
REMOTEHOST  DEFAULT=localhost          OVERRIDE=@{PAM_RHOST}
DISPLAY     DEFAULT=${REMOTEHOST}:0.0  OVERRIDE=${DISPLAY}

The first line sets the value of the REMOTEHOST variable to localhost, which is used whenever pam_env cannot determine any other value. The DISPLAY variable in turn contains the value of REMOTEHOST. Find more information in the comments in /etc/security/pam_env.conf.

2.4.2 pam_mount.conf.xml

The purpose of pam_mount is to mount user home directories during the login process, and to unmount them during logout in an environment where a central file server keeps all the home directories of users. With this method, it is not necessary to mount a complete /home directory where all the user home directories would be accessible. Instead, only the home directory of the user who is about to log in, is mounted.

After installing pam_mount, a template for pam_mount.conf.xml is available in /etc/security. The description of the various elements can be found in the manual page man 5 pam_mount.conf.

A basic configuration of this feature can be done with YaST. Select Network Settings › Windows Domain Membership › Expert Settings to add the file server; see Section 28.5, “Configuring Clients”.

2.4.3 limits.conf

System limits can be set on a user or group basis in limits.conf, which is read by the pam_limits module. The file allows you to set hard limits, which may not be exceeded, and soft limits, which may be exceeded temporarily. For more information about the syntax and the options, see the comments in /etc/security/limits.conf.

2.5 Configuring PAM Using pam-config

The pam-config tool helps you configure the global PAM configuration files (/etc/pam.d/common-*) and several selected application configurations. For a list of supported modules, use the pam-config --list-modules command. Use the pam-config command to maintain your PAM configuration files. Add new modules to your PAM configurations, delete other modules or modify options to these modules. When changing global PAM configuration files, no manual tweaking of the PAM setup for individual applications is required.

A simple use case for pam-config involves the following:

  1. Auto-generate a fresh Unix-style PAM configuration.  Let pam-config create the simplest possible setup which you can extend later on. The pam-config --create command creates a simple Unix authentication configuration. Pre-existing configuration files not maintained by pam-config are overwritten, but backup copies are kept as *.pam-config-backup.

  2. Add a new authentication method.  Adding a new authentication method (for example, LDAP) to your stack of PAM modules comes down to a simple pam-config --add --ldap command. LDAP is added wherever appropriate across all common-*-pc PAM configuration files.

  3. Add debugging for test purposes.  To make sure the new authentication procedure works as planned, turn on debugging for all PAM-related operations. The pam-config --add --ldap-debug turns on debugging for LDAP-related PAM operations. Find the debugging output in the systemd journal (see Chapter 15, journalctl: Query the systemd Journal).

  4. Query your setup.  Before you finally apply your new PAM setup, check if it contains all the options you wanted to add. The pam-config --query -- MODULE lists both the type and the options for the queried PAM module.

  5. Remove the debug options.  Finally, remove the debug option from your setup when you are entirely satisfied with the performance of it. The pam-config --delete --ldap-debug command turns off debugging for LDAP authentication. In case you had debugging options added for other modules, use similar commands to turn these off.

For more information on the pam-config command and the options available, refer to the manual page of pam-config(8).

2.6 Manually Configuring PAM

If you prefer to manually create or maintain your PAM configuration files, make sure to disable pam-config for these files.

When you create your PAM configuration files from scratch using the pam-config --create command, it creates symbolic links from the common-* to the common-*-pc files. pam-config only modifies the common-*-pc configuration files. Removing these symbolic links effectively disables pam-config, because pam-config only operates on the common-*-pc files and these files are not put into effect without the symbolic links.

Warning
Warning: Include pam_systemd.so into Configuration

If you are creating your own PAM configuration, make sure to include a session optional pam_systemd.so. Not including the pam_systemd.so can cause problems with systemd task limits. For details, refer to the man page of pam_systemd.so.

2.7 For More Information

In the /usr/share/doc/packages/pam directory after installing the pam-doc package, find the following additional documentation:

READMEs

In the top level of this directory, there is the modules subdirectory holding README files about the available PAM modules.

The Linux-PAM System Administrators' Guide

This document comprises everything that the system administrator should know about PAM. It discusses a range of topics, from the syntax of configuration files to the security aspects of PAM.

The Linux-PAM Module Writers' Manual

This document summarizes the topic from the developer's point of view, with information about how to write standard-compliant PAM modules.

The Linux-PAM Application Developers' Guide

This document comprises everything needed by an application developer who wants to use the PAM libraries.

The PAM Manual Pages

PAM in general and the individual modules come with manual pages that provide a good overview of the functionality of all the components.

3 Using NIS

  • Filename: security_nis.xml
  • ID: cha.nis
Abstract

When multiple Unix systems in a network access common resources, it becomes imperative that all user and group identities are the same for all machines in that network. The network should be transparent to users: their environments should not vary, regardless of which machine they are actually using. This can be done by means of NIS and NFS services. NFS distributes file systems over a network and is discussed in Chapter 27, Sharing File Systems with NFS.

NIS (Network Information Service) can be described as a database-like service that provides access to the contents of /etc/passwd, /etc/shadow, and /etc/group across networks. NIS can also be used for other purposes (making the contents of files like /etc/hosts or /etc/services available, for example), but this is beyond the scope of this introduction. People often refer to NIS as YP, because it works like the network's yellow pages.

3.1 Configuring NIS Servers

To distribute NIS information across networks, either install one single server (a master) that serves all clients, or NIS slave servers requesting this information from the master and relaying it to their respective clients.

3.1.1 Configuring a NIS Master Server

To manage the NIS Server functionality with YaST, install the yast2-nis-server package by running the zypper in yast2-nis-server command as root. To configure a NIS master server for your network, proceed as follows:

  1. Start YaST › Network Services › NIS Server.

  2. If you need just one NIS server in your network or if this server is to act as the master for further NIS slave servers, select Install and Set Up NIS Master Server. YaST installs the required packages.

    Tip
    Tip: Already Installed NIS Server Software

    If NIS server software is already installed on your machine, initiate the creation of a NIS master server by clicking Create NIS Master Server.

    NIS Server Setup
    Figure 3.1: NIS Server Setup
  3. Determine basic NIS setup options:

    1. Enter the NIS domain name.

    2. Define whether the host should also be a NIS client (enabling users to log in and access data from the NIS server) by selecting This Host is also a NIS Client.

    3. If your NIS server needs to act as a master server to NIS slave servers in other subnets, select Active Slave NIS Server Exists.

      The option Fast Map Distribution is only useful with Active Slave NIS Servers Exist. It speeds up the transfer of maps to the slaves.

    4. Select Allow Changes to Passwords to allow users in your network (both local users and those managed through the NIS server) to change their passwords on the NIS server (with the command yppasswd). This makes the options Allow Changes to GECOS Field and Allow Changes to Login Shell available. GECOS means that the users can also change their names and address settings with the command ypchfn. Shell allows users to change their default shell with the command ypchsh (for example, to switch from Bash to sh). The new shell must be one of the predefined entries in /etc/shells.

    5. Select Open Port in Firewall to have YaST adapt the firewall settings for the NIS server.

      Master Server Setup
      Figure 3.2: Master Server Setup
    6. Leave this dialog with Next or click Other Global Settings to make additional settings.

      Other Global Settings include changing the source directory of the NIS server (/etc by default). In addition, passwords can be merged here. The setting should be Yes to create the user database from the system authentication files /etc/passwd, /etc/shadow, and /etc/group. Also, determine the smallest user and group ID that should be offered by NIS. Click OK to confirm your settings and return to the previous screen.

      Changing the Directory and Synchronizing Files for a NIS Server
      Figure 3.3: Changing the Directory and Synchronizing Files for a NIS Server
  4. If you previously enabled Active Slave NIS Server Exists, enter the host names used as slaves and click Next. If no slave servers exist, this configuration step is skipped.

  5. Continue to the dialog for the database configuration. Specify the NIS Server Maps, the partial databases to transfer from the NIS server to the client. The default settings are usually adequate. Leave this dialog with Next.

  6. Check which maps should be available and click Next to continue.

    NIS Server Maps Setup
    Figure 3.4: NIS Server Maps Setup
  7. Determine which hosts are allowed to query the NIS server. You can add, edit, or delete hosts by clicking the appropriate button. Specify from which networks requests can be sent to the NIS server. Normally, this is your internal network. In this case, there should be the following two entries:

    255.0.0.0     127.0.0.0
    0.0.0.0       0.0.0.0

    The first entry enables connections from your own host, which is the NIS server. The second one allows all hosts to send requests to the server.

    Setting Request Permissions for a NIS Server
    Figure 3.5: Setting Request Permissions for a NIS Server
  8. Click Finish to save your changes and exit the setup.

3.1.2 Configuring a NIS Slave Server

To configure additional NIS slave servers in your network, proceed as follows:

  1. Start YaST › Network Services › NIS Server.

  2. Select Install and Set Up NIS Slave Server and click Next.

    Tip
    Tip

    If NIS server software is already installed on your machine, initiate the creation of a NIS slave server by clicking Create NIS Slave Server.

  3. Complete the basic setup of your NIS slave server:

    1. Enter the NIS domain.

    2. Enter host name or IP address of the master server.

    3. Set This Host is also a NIS Client if you want to enable user logins on this server.

    4. Adapt the firewall settings with Open Ports in Firewall.

    5. Click Next.

  4. Enter the hosts that are allowed to query the NIS server. You can add, edit, or delete hosts by clicking the appropriate button. Specify all networks from which requests can be sent to the NIS server. If it applies to all networks, use the following configuration:

    255.0.0.0     127.0.0.0
    0.0.0.0       0.0.0.0

    The first entry enables connections from your own host, which is the NIS server. The second one allows all hosts with access to the same network to send requests to the server.

  5. Click Finish to save changes and exit the setup.

3.2 Configuring NIS Clients

To use NIS on a workstation, do the following:

  1. Start YaST › Network Services › NIS Client.

  2. Activate the Use NIS button.

  3. Enter the NIS domain. This is usually a domain name given by your administrator or a static IP address received by DHCP. For information about DHCP, see Chapter 26, DHCP.

    Setting Domain and Address of a NIS Server
    Figure 3.6: Setting Domain and Address of a NIS Server
  4. Enter your NIS servers and separate their addresses by spaces. If you do not know your NIS server, click Find to let YaST search for any NIS servers in your domain. Depending on the size of your local network, this may be a time-consuming process. Broadcast asks for a NIS server in the local network after the specified servers fail to respond.

  5. Depending on your local installation, you may also want to activate the automounter. This option also installs additional software if required.

  6. If you do not want other hosts to be able to query which server your client is using, go to the Expert settings and disable Answer Remote Hosts. By checking Broken Server, the client is enabled to receive replies from a server communicating through an unprivileged port. For further information, see man ypbind.

  7. Click Finish to save them and return to the YaST control center. Your client is now configured with NIS.

4 Setting Up Authentication Servers and Clients Using YaST

  • Filename: security_auth.xml
  • ID: cha.security.auth
Abstract

The Authentication Server is based on LDAP and optionally Kerberos. On SUSE Linux Enterprise Server you can configure it with a YaST wizard.

For more information about LDAP, see Chapter 5, LDAP—A Directory Service, and about Kerberos, see Chapter 6, Network Authentication with Kerberos.

4.1 Configuring an Authentication Server with YaST

4.1.1 Initial Configuration of an Authentication Server

To set up an authentication server for user account data, make sure the yast2-auth-server, openldap2, krb5-server, and krb5-client packages are installed; YaST will remind you and install them if one of these packages is missing. For Kerberos support, the krb5-plugin-kdb-ldap package is required.

The first part of the Authentication Server configuration with YaST is setting up an LDAP server, then you can enable Kerberos.

Procedure 4.1: Authentication Server Configuration with YaST
  1. Start YaST as root and select Network Services › Authentication Server to invoke the configuration wizard.

  2. Configure the Global Settings of your LDAP server (you can change these settings later)—see Figure 4.1, “YaST Authentication Server Configuration”:

    YaST Authentication Server Configuration
    Figure 4.1: YaST Authentication Server Configuration
    1. Set LDAP to be started.

    2. If the LDAP server should announce its services via SLP, check Register at an SLP Daemon.

    3. Configure Firewall Settings.

    4. Click Next.

  3. Select the server type: Stand-alone server, Master server in a replication setup, or Replica (slave) server.

  4. Select security options (TLS Settings).

    It is strongly recommended to Enable TLS. For more information, see Procedure 4.2, “Editing Authentication Server Configuration”, Step 4.

    Warning
    Warning: Authentication Without Encryption

    When using authentication without enabling transport encryption using TLS, the password will be transmitted in the clear.

    Also consider using LDAP over SSL with certificates.

  5. Confirm Basic Database Settings with entering an LDAP Administrator Password and then clicking Next—see Figure 4.2, “YaST LDAP Server—New Database”.

    YaST LDAP Server—New Database
    Figure 4.2: YaST LDAP Server—New Database
  6. In the Kerberos Authentication dialog, decide whether to enable Kerberos authentication or not (you can change these settings later)—see Figure 4.3, “YaST Kerberos Authentication”.

    YaST Kerberos Authentication
    Figure 4.3: YaST Kerberos Authentication
  7. Choose whether Kerberos support is needed or not. If you enable it, also specify your Realm. Then confirm with Next.

    1. The Advanced Configuration allows you to specify various aspects such as Maximum ticket life time or ports to use.

  8. Finally, check the Authentication Server Configuration Summary and click Finish to exit the configuration wizard.

4.1.2 Editing an Authentication Server Configuration with YaST

For changes or additional configuration start the Authentication Server module again and in the left pane expand Global Settings to make subentries visible—see Figure 4.4, “YaST Editing Authentication Server Configuration”:

YaST Editing Authentication Server Configuration
Figure 4.4: YaST Editing Authentication Server Configuration
Procedure 4.2: Editing Authentication Server Configuration
  1. With Log Level Settings, configure the degree of logging activity (verbosity) of the LDAP server. From the predefined list, select or deselect logging options according to your needs. The more options are enabled, the larger your log files grow.

  2. Configure which connection types the server should offer under Allow/Disallow Features. Choose from:

    LDAPv2 Bind Requests

    This option enables connection requests (bind requests) from clients using the previous version of the protocol (LDAPv2).

    Anonymous Bind When Credentials Not Empty

    Normally, the LDAP server denies any authentication attempts with empty credentials, that is, a distinguished name (DN) or a password. However, enabling this option makes it possible to connect with a password and no DN to establish an anonymous connection.

    Unauthenticated Bind When DN Not Empty

    Enabling this option makes it possible to connect without authentication (anonymously) using a distinguished name (DN) but no password.

    Unauthenticated Update Options to Process

    Enabling this option allows non-authenticated (anonymous) update operations. Access is restricted according to ACLs and other rules.

  3. Allow/Disallow Features also lets you configure the server flags. Choose from:

    Disable Acceptance of Anonymous Bind Requests

    The server will no longer accept anonymous bind requests. Note, that this does not generally prohibit anonymous directory access.

    Disable Simple Bind Authentication

    Completely disable Simple Bind authentication.

    Disable Forcing Session to Anonymous Status upon StartTLS Operation Receipt

    The server will no longer force an authenticated connection back to the anonymous state when receiving the StartTLS operation.

    Disallow the StartTLS Operation if Authenticated

    The server will disallow the StartTLS operation on already authenticated connections.

  4. To configure secure communication between client and server, proceed with TLS Settings:

    1. Activate Enable TLS to enable TLS and SSL encryption of the client/server communication.

    2. Either Import Certificate by specifying the exact path to its location or enable the Use Common Server Certificate. If the Use Common Server Certificate is not available, because it has not been created during installation, go for Launch CA Management Module first—for more information, see Section 17.2, “YaST Modules for CA Management”.

Add Schema files to be included in the server's configuration by selecting Schema Files in the left part of the dialog. The default selection of schema files applies to the server providing a source of YaST user account data.

YaST allows to add traditional Schema files (usually with a name ending in .schema) or LDIF files containing Schema definitions in OpenLDAP's LDIF Schema format.

YaST Authentication Server Database Configuration
Figure 4.5: YaST Authentication Server Database Configuration

To configure the databases managed by your LDAP server, proceed as follows:

  1. Select the Databases item in the left part of the dialog.

  2. Click Add Database to add a new database.

  3. Specify the requested data:

    Base DN

    Enter the base DN (distinguished name) of your LDAP server.

    Administrator DN

    Enter the DN of the administrator in charge of the server. If you check Append Base DN, only provide the cn of the administrator and the system fills in the rest automatically.

    LDAP Administrator Password

    Enter the password for the database administrator.

    Use This Database as the Default for OpenLDAP Clients

    For convenience, check this option if wanted.

  4. In the next dialog, configure replication settings.

  5. In the next dialog, enable enforcement of password policies to provide extra security to your LDAP server:

    1. Check Enable Password Policies to be able to specify a password policy.

    2. Activate Hash Clear Text Passwords to have clear text passwords be hashed before they are written to the database whenever they are added or modified.

    3. Disclose "Account Locked" Status provides a relevant error message for bind requests to locked accounts.

      Warning
      Warning: Locked Accounts in Security Sensitive Environments

      Do not use the Disclose "Account Locked" Status option if your environment is sensitive to security issues, because the Locked Account error message provides security-sensitive information that can be exploited by a potential attacker.

    4. Enter the DN of the default policy object. To use a DN other than the one suggested by YaST, enter your choice. Otherwise, accept the default settings.

  6. Complete the database configuration by clicking Finish.

If you have not opted for password policies, your server is ready to run at this point. If you have chosen to enable password policies, proceed with the configuration of the password policy in detail. If you have chosen a password policy object that does not yet exist, YaST creates one:

  1. Enter the LDAP server password. In the navigation tree below Databases expand your database object and activate the Password Policy Configuration item.

  2. Make sure Enable Password Policies is activated. Then click Edit Policy.

  3. Configure the password change policies:

    1. Determine the number of passwords stored in the password history. Saved passwords may not be reused by the user.

    2. Determine if users can change their passwords and if they will need to change their passwords after a reset by the administrator. Require the old password for password changes (optional).

    3. Determine whether and to what extent passwords should be subject to quality checking. Set the minimum password length that must be met before a password is valid. If you select Accept Uncheckable Passwords, users are allowed to use encrypted passwords, even though the quality checks cannot be performed. If you opt for Only Accept Checked Passwords only those passwords that pass the quality tests are accepted as valid.

  4. Configure the password time-limit policies:

    1. Determine the minimum password time-limit (the time that needs to pass between two valid password changes) and the maximum password time limit.

    2. Determine the time between a password expiration warning and the actual password expiration.

    3. Set the number of postponement uses of an expired password before the password expires permanently.

  5. Configure the lockout policies:

    1. Enable password locking.

    2. Determine the number of bind failures that trigger a password lock.

    3. Determine the duration of the password lock.

    4. Determine the length of time that password failures are kept in the cache before they are purged.

  6. Apply your password policy settings with OK.

To edit a previously created database, select its base DN in the tree to the left. In the right part of the window, YaST displays a dialog similar to the one used for the creation of a new database (with the main difference that the base DN entry is grayed out and cannot be changed).

After leaving the Authentication Server configuration by selecting Finish, you are ready to go with a basic working configuration for your Authentication Server. To fine-tune this setup, use OpenLDAP's dynamic configuration back-end.

The OpenLDAP's dynamic configuration back-end stores the configuration in an LDAP database. That database consists of a set of .ldif files in /etc/openldap/slapd.d. There is no need to access these files directly. To access the settings you can either use the YaST Authentication Server module (the yast2-auth-server package) or an LDAP client such as ldapmodify or ldapsearch. For more information on the dynamic configuration of OpenLDAP, see the OpenLDAP Administration Guide.

4.1.3 Editing LDAP Users and Groups

For editing LDAP users and groups with YaST, see Section 5.4, “Configuring LDAP Users and Groups in YaST”.

4.2 Configuring an Authentication Client with YaST

YaST allows setting up authentication to clients using different modules:

4.3 SSSD

Two of the YaST modules are based on SSSD: User Logon Management and LDAP and Kerberos Authentication.

SSSD stands for System Security Services Daemon. SSSD talks to remote directory services that provide user data and provides various authentication methods, such as LDAP, Kerberos, or Active Directory (AD). It also provides an NSS (Name Service Switch) and PAM (Pluggable Authentication Module) interface.

SSSD can locally cache user data and then allow users to use the data, even if the real directory service is (temporarily) unreachable.

4.3.1 Checking the Status

After running one of the YaST authentication modules, you can check whether SSSD is running with:

systemctl status sssd
sssd.service - System Security Services Daemon
   Loaded: loaded (/usr/lib/systemd/system/sssd.service; enabled)
   Active: active (running) since Thu 2015-10-23 11:03:43 CEST; 5s ago
   [...]

4.3.2 Caching

To allow logging in when the authentication back-end is unavailable, SSSD will use its cache even if it was invalidated. This happens until the back-end is available again.

To invalidate the cache, run sss_cache -E (the command sss_cache is part of the package sssd-tools).

To completely remove the SSSD cache, run:

systemctl stop sssd
rm -f /var/lib/sss/db/*
systemctl start sssd

4.3.3 For More Information

For more information, see the SSSD man pages sssd.conf (man sssd.conf) and sssd (man sssd). There are also man pages for most SSSD modules.

5 LDAP—A Directory Service

  • Filename: security_ldap.xml
  • ID: cha.security.ldap
Abstract

The Lightweight Directory Access Protocol (LDAP) is a set of protocols designed to access and maintain information directories. LDAP can be used for user and group management, system configuration management, address management, and more. This chapter provides a basic understanding of how OpenLDAP works.

In a network environment, it is crucial to keep important information structured and to serve it quickly. A directory service keeps information available in a well-structured and searchable form.

Ideally, a central server stores the data in a directory and distributes it to all clients using a well-defined protocol. The structured data allow a wide range of applications to access them. A central repository reduces the necessary administrative effort. The use of an open and standardized protocol like LDAP ensures that as many client applications as possible can access such information.

A directory in this context is a type of database optimized for quick and effective reading and searching:

  • To make multiple concurrent reading accesses possible, the number of updates is usually very low. The number of read and write accesses is often limited to a few users with administrative privileges. In contrast, conventional databases are optimized for accepting the largest possible data volume in a short time.

  • When static data is administered, updates of the existing data sets are very rare. When working with dynamic data, especially when data sets like bank accounts or accounting are concerned, the consistency of the data is of primary importance. If an amount should be subtracted from one place to be added to another, both operations must happen concurrently, within one transaction, to ensure balance over the data stock. Traditional relational databases usually have a very strong focus on data consistency, such as the referential integrity support of transactions. Conversely, short-term inconsistencies are usually acceptable in LDAP directories. LDAP directories often do not have the same strong consistency requirements as relational databases.

The design of a directory service like LDAP is not laid out to support complex update or query mechanisms. All applications are guaranteed to access this service quickly and easily.

5.1 LDAP versus NIS

Unix system administrators traditionally use NIS (Network Information Service) for name resolution and data distribution in a network. The configuration data contained in the files group, hosts, mail, netgroup, networks, passwd, printcap, protocols, rpc, and services in the /etc directory is distributed to clients all over the network. These files can be maintained without major effort because they are simple text files. The handling of larger amounts of data, however, becomes increasingly difficult because of nonexistent structuring. NIS is only designed for Unix platforms, and is not suitable as a centralized data administration tool in heterogeneous networks.

Unlike NIS, the LDAP service is not restricted to pure Unix networks. Windows™ servers (starting with Windows 2000) support LDAP as a directory service. The application tasks mentioned above are additionally supported in non-Unix systems.

The LDAP principle can be applied to any data structure that needs to be centrally administered. A few application examples are:

  • Replacement for the NIS service

  • Mail routing (postfix)

  • Address books for mail clients, like Mozilla Thunderbird, Evolution, and Outlook

  • Administration of zone descriptions for a BIND 9 name server

  • User authentication with Samba in heterogeneous networks

This list can be extended because LDAP is extensible, unlike NIS. The clearly-defined hierarchical structure of the data simplifies the administration of large amounts of data, as it can be searched more easily.

5.2 Structure of an LDAP Directory Tree

To get background knowledge on how an LDAP server works and how the data is stored, it is vital to understand the way the data is organized on the server and how this structure enables LDAP to provide fast access to the data. To successfully operate an LDAP setup, you also need to be familiar with some basic LDAP terminology. This section introduces the basic layout of an LDAP directory tree and provides the basic terminology used with regard to LDAP. Skip this introductory section if you already have some LDAP background knowledge and only want to learn how to set up an LDAP environment in SUSE Linux Enterprise Server. Read on at Section 5.5, “Manually Configuring an LDAP Server”.

An LDAP directory has a tree structure. All entries (called objects) of the directory have a defined position within this hierarchy. This hierarchy is called the directory information tree (DIT). The complete path to the desired entry, which unambiguously identifies it, is called the distinguished name or DN. A single node along the path to this entry is called relative distinguished name or RDN.

The relations within an LDAP directory tree become more evident in the following example, shown in Figure 5.1, “Structure of an LDAP Directory”.

Structure of an LDAP Directory
Figure 5.1: Structure of an LDAP Directory

The complete diagram is a fictional directory information tree. The entries on three levels are depicted. Each entry corresponds to one box in the image. The complete, valid distinguished name for the fictional employee Geeko Linux, in this case, is cn=Geeko Linux,ou=doc,dc=example,dc=com. It is composed by adding the RDN cn=Geeko Linux to the DN of the preceding entry ou=doc,dc=example,dc=com.

The types of objects that can be stored in the DIT are globally determined following a Schema. The type of an object is determined by the object class. The object class determines what attributes the relevant object must or can be assigned. The Schema, therefore, must contain definitions of all object classes and attributes used in the desired application scenario. There are a few common Schemas (see RFC 2252 and 2256). The LDAP RFC defines a few commonly used Schemas (see for example, RFC4519). Additionally, Schemas are available for many other use cases (for example, Samba or NIS replacement). It is, however, possible to create custom Schemas or to use multiple Schemas complementing each other (if this is required by the environment in which the LDAP server should operate).

Table 5.1, “Commonly Used Object Classes and Attributes” offers a small overview of the object classes from core.schema and inetorgperson.schema used in the example, including required attributes (Req. Attr.) and valid attribute values.

Table 5.1: Commonly Used Object Classes and Attributes

Object Class

Meaning

Example Entry

Req. Attr.

dcObject

domainComponent (name components of the domain)

example

dc

organizationalUnit

organizationalUnit (organizational unit)

doc

ou

inetOrgPerson

inetOrgPerson (person-related data for the intranet or Internet)

Geeko Linux

sn and cn

Example 5.1, “Excerpt from schema.core” shows an excerpt from a Schema directive with explanations.

Example 5.1: Excerpt from schema.core
attributetype (2.5.4.11 NAME ( 'ou' 'organizationalUnitName') 1
       DESC 'RFC2256: organizational unit this object belongs to' 2
       SUP name ) 3

objectclass ( 2.5.6.5 NAME 'organizationalUnit' 4
       DESC 'RFC2256: an organizational unit' 5
       SUP top STRUCTURAL 6
       MUST ou 7
MAY (userPassword $ searchGuide $ seeAlso $ businessCategory 8
  $ x121Address $ registeredAddress $ destinationIndicator
  $ preferredDeliveryMethod $ telexNumber
  $ teletexTerminalIdentifier $ telephoneNumber
  $ internationaliSDNNumber $ facsimileTelephoneNumber
  $ street $ postOfficeBox $ postalCode $ postalAddress
  $ physicalDeliveryOfficeName
  $ st $ l $ description) )
  ...

The attribute type organizationalUnitName and the corresponding object class organizationalUnit serve as an example here.

1

The name of the attribute, its unique OID (object identifier) (numerical), and the abbreviation of the attribute.

2

A brief description of the attribute with DESC. The corresponding RFC, on which the definition is based, is also mentioned here.

3

SUP indicates a superordinate attribute type to which this attribute belongs.

4

The definition of the object class organizationalUnit begins—the same as in the definition of the attribute—with an OID and the name of the object class.

5

A brief description of the object class.

6

The SUP top entry indicates that this object class is not subordinate to another object class.

7

With MUST list all attribute types that must be used with an object of the type organizationalUnit.

8

With MAY list all attribute types that are permitted with this object class.

A very good introduction to the use of Schemas can be found in the OpenLDAP documentation (openldap2-doc). When installed, find it in /usr/share/doc/packages/openldap2/adminguide/guide.html.

5.3 Configuring an LDAP Client with YaST

YaST includes the module LDAP and Kerberos Client that helps define authentication scenarios involving either LDAP or Kerberos.

It can also be used to join Kerberos and LDAP separately. However, in many such cases, using this module may not be the first choice, such as for joining Active Directory (which uses a combination of LDAP and Kerberos). For more information, see Section 4.2, “Configuring an Authentication Client with YaST”.

Start the module by selecting Network Services › LDAP and Kerberos Client.

LDAP and Kerberos Client Window
Figure 5.2: LDAP and Kerberos Client Window

To configure an LDAP client, follow the procedure below:

  1. In the window LDAP and Kerberos Client, click Change Settings.

    Make sure that the tab Use a Directory as Identity Provider (LDAP) is chosen.

  2. Specify one or more LDAP server URLs, host names, or IP addresses under Enter LDAP server locations. When specifying multiple addresses, separate them with spaces.

  3. Specify the appropriate LDAP distinguished name (DN) under DN of Search Base. For example, a valid entry could be dc=example,dc=com.

  4. If your LDAP server supports TLS encryption, choose the appropriate security option under Secure LDAP Connection.

    To first ask the server whether it supports TLS encryption and be able to downgrade to an unencrypted connection if it does not, use Secure Communication via StartTLS.

  5. Activate other options as necessary:

    • You can Allow users to authenticate via LDAP and Automatically Create Home Directories on the local computer for them.

    • Use Cache LDAP Entries For Faster Response to cache LDAP entries locally. However, this bears the danger that entries can be slightly out of date.

    • Specify the types of data that should be used from the LDAP source, such as Users and Groups, Super-User Commands, and Network Disk Locations (network-shared drives that can be automatically mounted on request).

    • Specify the distinguished name (DN) and password of the user under whose name you want to bind to the LDAP directory in DN of Bind User and Password of the Bind User.

      Otherwise, if the server supports it, you can also leave both text boxes empty to bind anonymously to the server.

      Warning
      Warning: Authentication Without Encryption

      When using authentication without enabling transport encryption using TLS or StartTLS, the password will be transmitted in the clear.

    Under Extended Options, you can additionally configure timeouts for BIND operations.

  6. To check whether the LDAP connection works, click Test Connection.

  7. To leave the dialog, click OK. Then wait for the setup to complete.

    Finally, click Finish.

5.4 Configuring LDAP Users and Groups in YaST

The actual registration of user and group data differs only slightly from the procedure when not using LDAP. The following instructions relate to the administration of users. The procedure for administering groups is analogous.

  1. Access the YaST user administration with Security and Users › User and Group Management.

  2. Use Set Filter to limit the view of users to the LDAP users and enter the password for Root DN.

  3. Click Add to enter the user configuration. A dialog with four tabs opens:

    1. Specify the user's name, login name, and password in the User Data tab.

    2. Check the Details tab for the group membership, login shell, and home directory of the new user. If necessary, change the default to values that better suit your needs.

    3. Modify or accept the default Password Settings.

    4. Enter the Plug-Ins tab, select the LDAP plug-in, and click Launch to configure additional LDAP attributes assigned to the new user.

  4. Click OK to apply your settings and leave the user configuration.

The initial input form of user administration offers LDAP Options. This allows you to apply LDAP search filters to the set of available users. Alternatively open the module for configuring LDAP users and groups by selecting LDAP User and Group Configuration.

5.5 Manually Configuring an LDAP Server

YaST uses OpenLDAP's dynamic configuration database (back-config) to store the LDAP server's configuration. For details about the dynamic configuration back-end, see the slapd-config(5) man page or the OpenLDAP Software 2.4 Administrator's Guide located at /usr/share/doc/packages/openldap2/guide/admin/guide.html on your system if the openldap2 package is installed.

Tip
Tip: Upgrading an Old OpenLDAP Installation

YaST does not use /etc/openldap/slapd.conf to store the OpenLDAP configuration anymore. In case of a system upgrade, a copy of the original /etc/openldap/slapd.conf file will get created as /etc/openldap/slapd.conf.YaSTsave.

To conveniently access the configuration back-end, you use SASL external authentication. For example, the following ldapsearch command executed as root can show the complete slapd configuration:

ldapsearch -Y external -H ldapi:/// -b cn=config
Note
Note: LDAP Server Is Part of the Authentication Server

Basic LDAP Server initialization and configuration can be done within the Authentication Server YaST module. For more information, see Section 4.1, “Configuring an Authentication Server with YaST”.

When the LDAP server is fully configured and all desired entries have been made according to the pattern described in Section 5.6, “Manually Administering LDAP Data”, start the LDAP server as root by entering sudo systemctl start slapd. To stop the server manually, enter the command sudo systemctl stop slapd. Query the status of the running LDAP server with sudo systemctl status slapd.

Use the YaST Services Manager, described in Section 13.4, “Managing Services with YaST”, to have the server started and stopped automatically on system bootup and shutdown. You can also create the corresponding links to the start and stop scripts with the systemctl commands as described in Section 13.2.1, “Managing Services in a Running System”.

5.6 Manually Administering LDAP Data

OpenLDAP offers a series of tools for the administration of data in the LDAP directory. The four most important tools for adding to, deleting from, searching through and modifying the data stock are explained in this section.

5.6.1 Inserting Data into an LDAP Directory

Once your LDAP server is correctly configured (it features appropriate entries for suffix, directory, rootdn, rootpw and index), proceed to entering records. OpenLDAP offers the ldapadd command for this task. If possible, add the objects to the database in bundles (for practical reasons). LDAP can process the LDIF format (LDAP data interchange format) for this. An LDIF file is a simple text file that can contain an arbitrary number of attribute and value pairs. The LDIF file for creating a rough framework for the example in Figure 5.1, “Structure of an LDAP Directory” would look like the one in Example 5.2, “An LDIF File”.

Important
Important: Encoding of LDIF Files

LDAP works with UTF-8 (Unicode). Umlauts must be encoded correctly. Otherwise, avoid umlauts and other special characters or use iconv to convert the input to UTF-8.

Example 5.2: An LDIF File
# The Organization
dn: dc=example,dc=com
objectClass: dcObject
objectClass: organization
o: Example dc: example

# The organizational unit development (devel)
dn: ou=devel,dc=example,dc=com
objectClass: organizationalUnit
ou: devel

# The organizational unit documentation (doc)
dn: ou=doc,dc=example,dc=com
objectClass: organizationalUnit
ou: doc

# The organizational unit internal IT (it)
dn: ou=it,dc=example,dc=com
objectClass: organizationalUnit
ou: it

Save the file with the .ldif suffix then pass it to the server with the following command:

ldapadd -x -D DN_OF_THE_ADMINISTRATOR -W -f FILE.ldif

-x switches off the authentication with SASL in this case. -D declares the user that calls the operation. The valid DN of the administrator is entered here, as it has been configured in slapd.conf. In the current example, this is cn=Administrator,dc=example,dc=com. -W circumvents entering the password on the command line (in clear text) and activates a separate password prompt. The -f option passes the file name. See the details of running ldapadd in Example 5.3, “ldapadd with example.ldif”.

Example 5.3: ldapadd with example.ldif
ldapadd -x -D cn=Administrator,dc=example,dc=com -W -f example.ldif

Enter LDAP password:
adding new entry "dc=example,dc=com"
adding new entry "ou=devel,dc=example,dc=com"
adding new entry "ou=doc,dc=example,dc=com"
adding new entry "ou=it,dc=example,dc=com"

The user data of individuals can be prepared in separate LDIF files. Example 5.4, “LDIF Data for Tux” adds Tux to the new LDAP directory.

Example 5.4: LDIF Data for Tux
# coworker Tux
dn: cn=Tux Linux,ou=devel,dc=example,dc=com
objectClass: inetOrgPerson
cn: Tux Linux
givenName: Tux
sn: Linux
mail: tux@example.com
uid: tux
telephoneNumber: +49 1234 567-8

An LDIF file can contain an arbitrary number of objects. It is possible to pass directory branches (entirely or in part) to the server in one go, as shown in the example of individual objects. If it is necessary to modify some data relatively often, a fine subdivision of single objects is recommended.

5.6.2 Modifying Data in the LDAP Directory

The tool ldapmodify is provided for modifying the data stock. The easiest way to do this is to modify the corresponding LDIF file and pass the modified file to the LDAP server. To change the telephone number of colleague Tux from +49 1234 567-8 to +49 1234 567-10, edit the LDIF file like in Example 5.5, “Modified LDIF File tux.ldif”.

Example 5.5: Modified LDIF File tux.ldif
# coworker Tux
dn: cn=Tux Linux,ou=devel,dc=example,dc=com
changetype: modify
replace: telephoneNumber
telephoneNumber: +49 1234 567-10

Import the modified file into the LDAP directory with the following command:

ldapmodify -x -D cn=Administrator,dc=example,dc=com -W -f tux.ldif

Alternatively, pass the attributes to change directly to ldapmodify as follows:

  1. Start ldapmodify and enter your password:

    ldapmodify -x -D cn=Administrator,dc=example,dc=com -W
    Enter LDAP password:
  2. Enter the changes while carefully complying with the syntax in the order presented below:

    dn: cn=Tux Linux,ou=devel,dc=example,dc=com
    changetype: modify
    replace: telephoneNumber
    telephoneNumber: +49 1234 567-10

For more information about ldapmodify and its syntax, see the ldapmodify man page.

5.6.3 Searching or Reading Data from an LDAP Directory

OpenLDAP provides, with ldapsearch, a command line tool for searching data within an LDAP directory and reading data from it. This is a simple query:

ldapsearch -x -b dc=example,dc=com "(objectClass=*)"

The -b option determines the search base (the section of the tree within which the search should be performed). In the current case, this is dc=example,dc=com. To perform a more finely-grained search in specific subsections of the LDAP directory (for example, only within the devel department), pass this section to ldapsearch with -b. -x requests activation of simple authentication. (objectClass=*) declares that all objects contained in the directory should be read. This command option can be used after the creation of a new directory tree to verify that all entries have been recorded correctly and the server responds as desired. For more information about the use of ldapsearch, see the ldapsearch(1) man page.

5.6.4 Deleting Data from an LDAP Directory

Delete unwanted entries with ldapdelete. The syntax is similar to that of the other commands. To delete, for example, the complete entry for Tux Linux, issue the following command:

ldapdelete -x -D cn=Administrator,dc=example,dc=com -W cn=Tux \
Linux,ou=devel,dc=example,dc=com

5.7 For More Information

More complex subjects (like SASL configuration or establishment of a replicating LDAP server that distributes the workload among multiple slaves) were omitted from this chapter. Find detailed information about both subjects in the OpenLDAP 2.4 Administrator's Guide—see at OpenLDAP 2.4 Administrator's Guide.

The Web site of the OpenLDAP project offers exhaustive documentation for beginner and advanced LDAP users:

OpenLDAP Faq-O-Matic

A detailed question and answer collection applying to the installation, configuration, and use of OpenLDAP. Find it at http://www.openldap.org/faq/data/cache/1.html.

Quick Start Guide

Brief step-by-step instructions for installing your first LDAP server. Find it at http://www.openldap.org/doc/admin24/quickstart.html or on an installed system in Section 2 of /usr/share/doc/packages/openldap2/guide/admin/guide.html.

OpenLDAP 2.4 Administrator's Guide

A detailed introduction to all important aspects of LDAP configuration, including access controls and encryption. See http://www.openldap.org/doc/admin24/ or, on an installed system, /usr/share/doc/packages/openldap2/guide/admin/guide.html.

Understanding LDAP

A detailed general introduction to the basic principles of LDAP: http://www.redbooks.ibm.com/redbooks/pdfs/sg244986.pdf.

Printed literature about LDAP:

  • LDAP System Administration by Gerald Carter (ISBN 1-56592-491-6)

  • Understanding and Deploying LDAP Directory Services by Howes, Smith, and Good (ISBN 0-672-32316-8)

The ultimate reference material for the subject of LDAP are the corresponding RFCs (request for comments), 2251 to 2256.

6 Network Authentication with Kerberos

  • Filename: security_kerberos.xml
  • ID: cha.security.kerberos

An open network provides no means of ensuring that a workstation can identify its users properly, except through the usual password mechanisms. In common installations, the user must enter the password each time a service inside the network is accessed. Kerberos provides an authentication method with which a user registers only once and is trusted in the complete network for the rest of the session. To have a secure network, the following requirements must be met:

  • Have all users prove their identity for each desired service and make sure that no one can take the identity of someone else.

  • Make sure that each network server also proves its identity. Otherwise an attacker might be able to impersonate the server and obtain sensitive information transmitted to the server. This concept is called mutual authentication, because the client authenticates to the server and vice versa.

Kerberos helps you meet these requirements by providing strongly encrypted authentication. Only the basic principles of Kerberos are discussed here. For detailed technical instruction, refer to the Kerberos documentation.

6.1 Kerberos Terminology

The following glossary defines some Kerberos terminology.

credential

Users or clients need to present some kind of credentials that authorize them to request services. Kerberos knows two kinds of credentials—tickets and authenticators.

ticket

A ticket is a per-server credential used by a client to authenticate at a server from which it is requesting a service. It contains the name of the server, the client's name, the client's Internet address, a time stamp, a lifetime, and a random session key. All this data is encrypted using the server's key.

authenticator

Combined with the ticket, an authenticator is used to prove that the client presenting a ticket is really the one it claims to be. An authenticator is built using the client's name, the workstation's IP address, and the current workstation's time, all encrypted with the session key known only to the client and the relevant server. An authenticator can only be used once, unlike a ticket. A client can build an authenticator itself.

principal

A Kerberos principal is a unique entity (a user or service) to which it can assign a ticket. A principal consists of the following components:

USER/INSTANCE@REALM
  • primary:  The first part of the principal. In the case of users, this is usually the same as the user name.

  • instance (optional) Additional information characterizing the primary. This string is separated from the primary by a /.

    tux@example.org and tux/admin@example.org can both exist on the same Kerberos system and are treated as different principals.

  • realm:  Specifies the Kerberos realm. Normally, your realm is your domain name in uppercase letters.

mutual authentication

Kerberos ensures that both client and server can be sure of each other's identity. They share a session key, which they can use to communicate securely.

session key

Session keys are temporary private keys generated by Kerberos. They are known to the client and used to encrypt the communication between the client and the server for which it requested and received a ticket.

replay

Almost all messages sent in a network can be eavesdropped, stolen, and resent. In the Kerberos context, this would be most dangerous if an attacker manages to obtain your request for a service containing your ticket and authenticator. The attacker could then try to resend it (replay) to impersonate you. However, Kerberos implements several mechanisms to deal with this problem.

server or service

Service is used to refer to a specific action to perform. The process behind this action is called a server.

6.2 How Kerberos Works

Kerberos is often called a third-party trusted authentication service, which means all its clients trust Kerberos's judgment of another client's identity. Kerberos keeps a database of all its users and their private keys.

To ensure Kerberos is working correctly, run both the authentication and ticket-granting server on a dedicated machine. Make sure that only the administrator can access this machine physically and over the network. Reduce the (networking) services running on it to the absolute minimum—do not even run sshd.

6.2.1 First Contact

Your first contact with Kerberos is quite similar to any login procedure at a normal networking system. Enter your user name. This piece of information and the name of the ticket-granting service are sent to the authentication server (Kerberos). If the authentication server knows you, it generates a random session key for further use between your client and the ticket-granting server. Now the authentication server prepares a ticket for the ticket-granting server. The ticket contains the following information—all encrypted with a session key only the authentication server and the ticket-granting server know:

  • The names of both, the client and the ticket-granting server

  • The current time

  • A lifetime assigned to this ticket

  • The client's IP address

  • The newly-generated session key

This ticket is then sent back to the client together with the session key, again in encrypted form, but this time the private key of the client is used. This private key is only known to Kerberos and the client, because it is derived from your user password. Now that the client has received this response, you are prompted for your password. This password is converted into the key that can decrypt the package sent by the authentication server. The package is unwrapped and password and key are erased from the workstation's memory. As long as the lifetime given to the ticket used to obtain other tickets does not expire, your workstation can prove your identity.

6.2.2 Requesting a Service

To request a service from any server in the network, the client application needs to prove its identity to the server. Therefore, the application generates an authenticator. An authenticator consists of the following components:

  • The client's principal

  • The client's IP address

  • The current time

  • A checksum (chosen by the client)

All this information is encrypted using the session key that the client has already received for this special server. The authenticator and the ticket for the server are sent to the server. The server uses its copy of the session key to decrypt the authenticator, which gives it all the information needed about the client requesting its service, to compare it to that contained in the ticket. The server checks if the ticket and the authenticator originate from the same client.

Without any security measures implemented on the server side, this stage of the process would be an ideal target for replay attacks. Someone could try to resend a request stolen off the net some time before. To prevent this, the server does not accept any request with a time stamp and ticket received previously. In addition to that, a request with a time stamp differing too much from the time the request is received is ignored.

6.2.3 Mutual Authentication

Kerberos authentication can be used in both directions. It is not only a question of the client being the one it claims to be. The server should also be able to authenticate itself to the client requesting its service. Therefore, it sends an authenticator itself. It adds one to the checksum it received in the client's authenticator and encrypts it with the session key, which is shared between it and the client. The client takes this response as a proof of the server's authenticity and they both start cooperating.

6.2.4 Ticket Granting—Contacting All Servers

Tickets are designed to be used for one server at a time. Therefore, you need to get a new ticket each time you request another service. Kerberos implements a mechanism to obtain tickets for individual servers. This service is called the ticket-granting service. The ticket-granting service is a service (like any other service mentioned before) and uses the same access protocols that have already been outlined. Any time an application needs a ticket that has not already been requested, it contacts the ticket-granting server. This request consists of the following components:

  • The requested principal

  • The ticket-granting ticket

  • An authenticator

Like any other server, the ticket-granting server now checks the ticket-granting ticket and the authenticator. If they are considered valid, the ticket-granting server builds a new session key to be used between the original client and the new server. Then the ticket for the new server is built, containing the following information:

  • The client's principal

  • The server's principal

  • The current time

  • The client's IP address

  • The newly-generated session key

The new ticket has a lifetime, which is either the remaining lifetime of the ticket-granting ticket or the default for the service. The lesser of both values is assigned. The client receives this ticket and the session key, which are sent by the ticket-granting service. But this time the answer is encrypted with the session key that came with the original ticket-granting ticket. The client can decrypt the response without requiring the user's password when a new service is contacted. Kerberos can thus acquire ticket after ticket for the client without bothering the user.

6.3 User View of Kerberos

Ideally, a user only contact with Kerberos happens during login at the workstation. The login process includes obtaining a ticket-granting ticket. At logout, a user's Kerberos tickets are automatically destroyed, which makes it difficult for anyone else to impersonate this user.

The automatic expiration of tickets can lead to a situation when a user's login session lasts longer than the maximum lifespan given to the ticket-granting ticket (a reasonable setting is 10 hours). However, the user can get a new ticket-granting ticket by running kinit. Enter the password again and Kerberos obtains access to desired services without additional authentication. To get a list of all the tickets silently acquired for you by Kerberos, run klist.

Here is a short list of applications that use Kerberos authentication. These applications can be found under /usr/lib/mit/bin or /usr/lib/mit/sbin after installing the package krb5-apps-clients. They all have the full functionality of their common Unix and Linux brothers plus the additional bonus of transparent authentication managed by Kerberos:

  • telnet, telnetd

  • rlogin

  • rsh, rcp, rshd

  • ftp, ftpd

  • ksu

You no longer need to enter your password for using these applications because Kerberos has already proven your identity. ssh, if compiled with Kerberos support, can even forward all the tickets acquired for one workstation to another one. If you use ssh to log in to another workstation, ssh makes sure that the encrypted contents of the tickets are adjusted to the new situation. Simply copying tickets between workstations is not sufficient because the ticket contains workstation-specific information (the IP address). XDM and GDM offer Kerberos support, too. Read more about the Kerberos network applications in Kerberos V5 UNIX User's Guide at http://web.mit.edu/kerberos.

6.4 Installing and Administering Kerberos

A Kerberos environment consists of several components. A key distribution center (KDC) holds the central database with all Kerberos-relevant data. All clients rely on the KDC for proper authentication across the network. Both the KDC and the clients need to be configured to match your setup:

General Preparations

Check your network setup and make sure it meets the minimum requirements outlined in Section 6.4.1, “Kerberos Network Topology”. Choose an appropriate realm for your Kerberos setup, see Section 6.4.2, “Choosing the Kerberos Realms”. Carefully set up the machine that is to serve as the KDC and apply tight security, see Section 6.4.3, “Setting Up the KDC Hardware”. Set up a reliable time source in your network to make sure all tickets contain valid time stamps, see Section 6.4.4, “Configuring Time Synchronization”.

Basic Configuration

Configure the KDC and the clients, see Section 6.4.5, “Configuring the KDC” and Section 6.4.6, “Configuring Kerberos Clients”. Enable remote administration for your Kerberos service, so you do not need physical access to your KDC machine, see Section 6.4.7, “Configuring Remote Kerberos Administration”. Create service principals for every service in your realm, see Section 6.4.8, “Creating Kerberos Service Principals”.

Enabling Kerberos Authentication

Various services in your network can use Kerberos. To add Kerberos password-checking to applications using PAM, proceed as outlined in Section 6.4.9, “Enabling PAM Support for Kerberos”. To configure SSH or LDAP with Kerberos authentication, proceed as outlined in Section 6.4.10, “Configuring SSH for Kerberos Authentication” and Section 6.4.11, “Using LDAP and Kerberos”.

6.4.1 Kerberos Network Topology

Any Kerberos environment must meet the following requirements to be fully functional:

  • Provide a DNS server for name resolution across your network, so clients and servers can locate each other. Refer to Chapter 25, The Domain Name System for information on DNS setup.

  • Provide a time server in your network. Using exact time stamps is crucial to a Kerberos setup, because valid Kerberos tickets must contain correct time stamps. Refer to Chapter 24, Time Synchronization with NTP for information on NTP setup.

  • Provide a key distribution center (KDC) as the center piece of the Kerberos architecture. It holds the Kerberos database. Use the tightest possible security policy on this machine to prevent any attacks on this machine compromising your entire infrastructure.

  • Configure the client machines to use Kerberos authentication.

The following figure depicts a simple example network with only the minimum components needed to build a Kerberos infrastructure. Depending on the size and topology of your deployment, your setup may vary.

Kerberos Network Topology
Figure 6.1: Kerberos Network Topology
Tip
Tip: Configuring Subnet Routing

For a setup similar to the one in Figure 6.1, “Kerberos Network Topology”, configure routing between the two subnets (192.168.1.0/24 and 192.168.2.0/24). Refer to Section 16.4.1.5, “Configuring Routing” for more information on configuring routing with YaST.

6.4.2 Choosing the Kerberos Realms

The domain of a Kerberos installation is called a realm and is identified by a name, such as EXAMPLE.COM or simply ACCOUNTING. Kerberos is case-sensitive, so example.com is actually a different realm than EXAMPLE.COM. Use the case you prefer. It is common practice, however, to use uppercase realm names.

It is also a good idea to use your DNS domain name (or a subdomain, such as ACCOUNTING.EXAMPLE.COM). As shown below, your life as an administrator can be much easier if you configure your Kerberos clients to locate the KDC and other Kerberos services via DNS. To do so, it is helpful if your realm name is a subdomain of your DNS domain name.

Unlike the DNS name space, Kerberos is not hierarchical. So if you have a realm named EXAMPLE.COM with two subrealms named DEVELOPMENT and ACCOUNTING, and these subordinate realms do not inherit principals from EXAMPLE.COM. Instead, you would have three separate realms, and you would need to configure cross-realm authentication for each realm, so that users from one realm to interact with servers or other users from another realm.

For the sake of simplicity, let us assume you are setting up just one realm for your entire organization. For the remainder of this section, the realm name EXAMPLE.COM is used in all examples.

6.4.3 Setting Up the KDC Hardware

The first thing required to use Kerberos is a machine that acts as the key distribution center, or KDC for short. This machine holds the entire Kerberos user database with passwords and all information.

The KDC is the most important part of your security infrastructure—if someone breaks into it, all user accounts and all of your infrastructure protected by Kerberos is compromised. An attacker with access to the Kerberos database can impersonate any principal in the database. Tighten security for this machine as much as possible:

  1. Put the server machine into a physically secured location, such as a locked server room to which only a very few people have access.

  2. Do not run any network applications on it except the KDC. This includes servers and clients—for example, the KDC should not import any file systems via NFS or use DHCP to retrieve its network configuration.

  3. Install a minimal system first then check the list of installed packages and remove any unneeded packages. This includes servers, such as inetd, portmap, and CUPS, plus anything X-based. Even installing an SSH server should be considered a potential security risk.

  4. No graphical login is provided on this machine as an X server is a potential security risk. Kerberos provides its own administration interface.

  5. Configure /etc/nsswitch.conf to use only local files for user and group lookup. Change the lines for passwd and group to look like this:

    passwd:         files
    group:          files

    Edit the passwd, group, and shadow files in /etc and remove the lines that start with a + character (these are for NIS lookups).

  6. Disable all user accounts except root's account by editing /etc/shadow and replacing the hashed passwords with * or ! characters.

6.4.4 Configuring Time Synchronization

To use Kerberos successfully, make sure that all system clocks within your organization are synchronized within a certain range. This is important because Kerberos protects against replayed credentials. An attacker might be able to observe Kerberos credentials on the network and reuse them to attack the server. Kerberos employs several defenses to prevent this. One of them is that it puts time stamps into its tickets. A server receiving a ticket with a time stamp that differs from the current time rejects the ticket.

Kerberos allows a certain leeway when comparing time stamps. However, computer clocks can be very inaccurate in keeping time—it is not unheard of for PC clocks to lose or gain half an hour during a week. For this reason, configure all hosts on the network to synchronize their clocks with a central time source.

A simple way to do so is by installing an NTP time server on one machine and having all clients synchronize their clocks with this server. Do this either by running an NTP daemon in client mode on all these machines or by running ntpdate once a day from all clients (this solution probably works for a few clients only). The KDC itself needs to be synchronized to the common time source as well. Because running an NTP daemon on this machine would be a security risk, it is probably a good idea to do this by running ntpdate via a cron job. To configure your machine as an NTP client, proceed as outlined in Section 24.1, “Configuring an NTP Client with YaST”.

A different way to secure the time service and still use the NTP daemon is to attach a hardware reference clock to a dedicated NTP server and an additional hardware reference clock to the KDC.

It is also possible to adjust the maximum deviation Kerberos allows when checking time stamps. This value (called clock skew) can be set in the krb5.conf file as described in Section 6.4.6.3, “Adjusting the Clock Skew”.

6.4.5 Configuring the KDC

This section covers the initial configuration and installation of the KDC, including the creation of an administrative principal. This procedure consists of several steps:

  1. Install the RPMs.  On a machine designated as the KDC, install the following software packages: krb5, krb5-server and krb5-client packages.

  2. Adjust the Configuration Files.  The /etc/krb5.conf and /var/lib/kerberos/krb5kdc/kdc.conf configuration files must be adjusted for your scenario. These files contain all information on the KDC.

  3. Create the Kerberos Database.  Kerberos keeps a database of all principal identifiers and the secret keys of all principals that need to be authenticated. Refer to Section 6.4.5.1, “Setting Up the Database” for details.

  4. Adjust the ACL Files: Add Administrators.  The Kerberos database on the KDC can be managed remotely. To prevent unauthorized principals from tampering with the database, Kerberos uses access control lists. You must explicitly enable remote access for the administrator principal to enable them to manage the database. The Kerberos ACL file is located under /var/lib/kerberos/krb5kdc/kadm5.acl. Refer to Section 6.4.7, “Configuring Remote Kerberos Administration” for details.

  5. Adjust the Kerberos Database: Add Administrators.  You need at least one administrative principal to run and administer Kerberos. This principal must be added before starting the KDC. Refer to Section 6.4.5.2, “Creating a Principal” for details.

  6. Start the Kerberos Daemon.  After the KDC software is installed and properly configured, start the Kerberos daemon to provide Kerberos service for your realm. Refer to Section 6.4.5.3, “Starting the KDC” for details.

  7. Create a Principal for Yourself.  You need a principal for yourself. Refer to Section 6.4.5.2, “Creating a Principal” for details.

6.4.5.1 Setting Up the Database

Your next step is to initialize the database where Kerberos keeps all information about principals. Set up the database master key, which is used to protect the database from accidental disclosure (in particular if it is backed up to tape). The master key is derived from a pass phrase and is stored in a file called the stash file. This is so you do not need to enter the password every time the KDC is restarted. Make sure that you choose a good pass phrase, such as a sentence from a book opened to a random page.

When you make tape backups of the Kerberos database (/var/lib/kerberos/krb5kdc/principal), do not back up the stash file (which is in /var/lib/kerberos/krb5kdc/.k5.EXAMPLE.COM). Otherwise, everyone able to read the tape could also decrypt the database. Therefore, keep a copy of the pass phrase in a safe or some other secure location, because you will need it to restore your database from backup tape after a crash.

To create the stash file and the database, run:

kdb5_util create -r EXAMPLE.COM -s

You will see the following output:

Initializing database '/var/lib/kerberos/krb5kdc/principal' for realm 'EXAMPLE.COM',
master key name 'K/M@EXAMPLE.COM'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key:  1
Re-enter KDC database master key to verify:  2

1

Type the master password.

2

Type the password again.

To verify, use the list command:

kadmin.local

kadmin> listprincs

You will see several principals in the database, which are for internal use by Kerberos:

K/M@EXAMPLE.COM
kadmin/admin@EXAMPLE.COM
kadmin/changepw@EXAMPLE.COM
krbtgt/EXAMPLE.COM@EXAMPLE.COM

6.4.5.2 Creating a Principal

Create two Kerberos principals for yourself: one normal principal for everyday work and one for administrative tasks relating to Kerberos. Assuming your login name is exampleuserIII_plain, proceed as follows:

kadmin.local

kadmin> ank geeko

You will see the following output:

geeko@EXAMPLE.COM's Password: 1
Verifying password: 2

1

Type exampleuserIII_plain's password.

1

Type exampleuserIII_plain's password again.

Next, create another principal named geeko/admin by typing ank geeko/admin at the kadmin prompt. The admin suffixed to your user name is a role. Later, use this role when administering the Kerberos database. A user can have several roles for different purposes. Roles act like completely different accounts that have similar names.

6.4.5.3 Starting the KDC

Start the KDC daemon and the kadmin daemon. To start the daemons manually, enter:

sudo systemctl start krb5kdc
sudo systemctl start kadmind

Also make sure that the services KDC (krb5kdc) and kadmind (kadmind) are started by default when the server machine is rebooted. Enable them by entering:

sudo systemctl enable krb5kdc kadmind

or by using the YaST Services Manager.

6.4.6 Configuring Kerberos Clients

When the supporting infrastructure is in place (DNS, NTP) and the KDC has been properly configured and started, configure the client machines. To configure a Kerberos client, use one of the two manual approaches described below.

When configuring Kerberos, there are two approaches you can take—static configuration in the /etc/krb5.conf file or dynamic configuration with DNS. With DNS configuration, Kerberos applications try to locate the KDC services using DNS records. With static configuration, add the host names of your KDC server to krb5.conf (and update the file whenever you move the KDC or reconfigure your realm in other ways).

DNS-based configuration is generally a lot more flexible and the amount of configuration work per machine is a lot less. However, it requires that your realm name is either the same as your DNS domain or a subdomain of it. Configuring Kerberos via DNS also creates a security issue: an attacker can seriously disrupt your infrastructure through your DNS (by shooting down the name server, spoofing DNS records, etc.). However, this amounts to a denial of service at worst. A similar scenario applies to the static configuration case unless you enter IP addresses in krb5.conf instead of host names.

6.4.6.1 Static Configuration

One way to configure Kerberos is to edit /etc/krb5.conf. The file installed by default contains various sample entries. Erase all of these entries before starting. krb5.conf is made up of several sections (stanzas), each introduced by the section name in brackets like [this].

To configure your Kerberos clients, add the following stanza to krb5.conf (where kdc.example.com is the host name of the KDC):

[libdefaults]
        default_realm = EXAMPLE.COM

[realms]
        EXAMPLE.COM = {
                kdc = kdc.example.com
                admin_server = kdc.example.com
        }

The default_realm line sets the default realm for Kerberos applications. If you have several realms, add additional statements to the [realms] section.

Also add a statement to this file that tells applications how to map host names to a realm. For example, when connecting to a remote host, the Kerberos library needs to know in which realm this host is located. This must be configured in the [domain_realms] section:

[domain_realm]
.example.com = EXAMPLE.COM
www.example.org = EXAMPLE.COM

This tells the library that all hosts in the example.com DNS domains are in the EXAMPLE.COM Kerberos realm. In addition, one external host named www.example.org should also be considered a member of the EXAMPLE.COM realm.

6.4.6.2 DNS-Based Configuration

DNS-based Kerberos configuration makes heavy use of SRV records. See (RFC2052) A DNS RR for specifying the location of services at http://www.ietf.org.

The name of an SRV record, as far as Kerberos is concerned, is always in the format _service._proto.realm, where realm is the Kerberos realm. Domain names in DNS are case-insensitive, so case-sensitive Kerberos realms would break when using this configuration method. _service is a service name (different names are used when trying to contact the KDC or the password service, for example). _proto can be either _udp or _tcp, but not all services support both protocols.

The data portion of SRV resource records consists of a priority value, a weight, a port number, and a host name. The priority defines the order in which hosts should be tried (lower values indicate a higher priority). The weight value is there to support some sort of load balancing among servers of equal priority. You probably do not need any of this, so it is okay to set these to zero.

MIT Kerberos currently looks up the following names when looking for services:

_kerberos

This defines the location of the KDC daemon (the authentication and ticket granting server). Typical records look like this:

_kerberos._udp.EXAMPLE.COM.  IN  SRV    0 0 88 kdc.example.com.
_kerberos._tcp.EXAMPLE.COM.  IN  SRV    0 0 88 kdc.example.com.
_kerberos-adm

This describes the location of the remote administration service. Typical records look like this:

_kerberos-adm._tcp.EXAMPLE.COM. IN  SRV    0 0 749 kdc.example.com.

Because kadmind does not support UDP, there should be no _udp record.

As with the static configuration file, there is a mechanism to inform clients that a specific host is in the EXAMPLE.COM realm, even if it is not part of the example.com DNS domain. This can be done by attaching a TXT record to _kerberos.host_name, as shown here:

_kerberos.www.example.org.  IN TXT "EXAMPLE.COM"

6.4.6.3 Adjusting the Clock Skew

The clock skew is the tolerance for accepting tickets with time stamps that do not exactly match the host's system clock. Usually, the clock skew is set to 300 seconds (five minutes). This means a ticket can have a time stamp somewhere between five minutes behind and five minutes ahead of the server's clock.

When using NTP to synchronize all hosts, you can reduce this value to about one minute. The clock skew value can be set in /etc/krb5.conf like this:

[libdefaults]
        clockskew = 60

6.4.7 Configuring Remote Kerberos Administration

To be able to add and remove principals from the Kerberos database without accessing the KDC's console directly, tell the Kerberos administration server which principals are allowed to do what by editing /var/lib/kerberos/krb5kdc/kadm5.acl. The ACL (access control list) file allows you to specify privileges with a precise degree of control. For details, refer to the manual page with man 8 kadmind.

For now, grant yourself the privilege to administer the database by putting the following line into the file:

geeko/admin              *

Replace the user name exampleuserIII_plain with your own. Restart kadmind for the change to take effect.

You should now be able to perform Kerberos administration tasks remotely using the kadmin tool. First, obtain a ticket for your admin role and use that ticket when connecting to the kadmin server:

kadmin -p geeko/admin
Authenticating as principal geeko/admin@EXAMPLE.COM with password.
Password for geeko/admin@EXAMPLE.COM:
kadmin:  getprivs
current privileges: GET ADD MODIFY DELETE
kadmin:

Using the getprivs command, verify which privileges you have. The list shown above is the full set of privileges.

As an example, modify the principal exampleuserIII_plain:

kadmin -p geeko/admin
Authenticating as principal geeko/admin@EXAMPLE.COM with password.
Password for geeko/admin@EXAMPLE.COM:

kadmin:  getprinc geeko
Principal: geeko@EXAMPLE.COM
Expiration date: [never]
Last password change: Wed Jan 12 17:28:46 CET 2005
Password expiration date: [none]
Maximum ticket life: 0 days 10:00:00
Maximum renewable life: 7 days 00:00:00
Last modified: Wed Jan 12 17:47:17 CET 2005 (admin/admin@EXAMPLE.COM)
Last successful authentication: [never]
Last failed authentication: [never]
Failed password attempts: 0
Number of keys: 2
Key: vno 1, Triple DES cbc mode with HMAC/sha1, no salt
Key: vno 1, DES cbc mode with CRC-32, no salt
Attributes:
Policy: [none]

kadmin:  modify_principal -maxlife "8 hours" geeko
Principal "geeko@EXAMPLE.COM" modified.
kadmin:  getprinc geeko
Principal: geeko@EXAMPLE.COM
Expiration date: [never]
Last password change: Wed Jan 12 17:28:46 CET 2005
Password expiration date: [none]
Maximum ticket life: 0 days 08:00:00
Maximum renewable life: 7 days 00:00:00
Last modified: Wed Jan 12 17:59:49 CET 2005 (geeko/admin@EXAMPLE.COM)
Last successful authentication: [never]
Last failed authentication: [never]
Failed password attempts: 0
Number of keys: 2
Key: vno 1, Triple DES cbc mode with HMAC/sha1, no salt
Key: vno 1, DES cbc mode with CRC-32, no salt
Attributes:
Policy: [none]
kadmin:

This changes the maximum ticket life time to eight hours. For more information about the kadmin command and the options available, see the krb5-doc package or refer to the man 8 kadmin manual page.

6.4.8 Creating Kerberos Service Principals

So far, only user credentials have been discussed. However, Kerberos-compatible services usually need to authenticate themselves to the client user, too. Therefore, special service principals must be in the Kerberos database for each service offered in the realm. For example, if ldap.example.com offers an LDAP service, you need a service principal, ldap/ldap.example.com@EXAMPLE.COM, to authenticate this service to all clients.

The naming convention for service principals is SERVICE/HOSTNAME@REALM, where HOSTNAME is the host's fully qualified host name.

Valid service descriptors are:

Service Descriptor

Service

host

Telnet, RSH, SSH

nfs

NFSv4 (with Kerberos support)

HTTP

HTTP (with Kerberos authentication)

imap

IMAP

pop

POP3

ldap

LDAP

Service principals are similar to user principals, but have significant differences. The main difference between a user principal and a service principal is that the key of the former is protected by a password. When a user obtains a ticket-granting ticket from the KDC, they needs to type their password, so Kerberos can decrypt the ticket. It would be inconvenient for system administrators to obtain new tickets for the SSH daemon every eight hours or so.

Instead, the key required to decrypt the initial ticket for the service principal is extracted by the administrator from the KDC only once and stored in a local file called the keytab. Services such as the SSH daemon read this key and use it to obtain new tickets automatically, when needed. The default keytab file resides in /etc/krb5.keytab.

To create a host service principal for jupiter.example.com enter the following commands during your kadmin session:

kadmin -p geeko/admin
Authenticating as principal geeko/admin@EXAMPLE.COM with password.
Password for geeko/admin@EXAMPLE.COM:
kadmin:  addprinc -randkey host/jupiter.example.com
WARNING: no policy specified for host/jupiter.example.com@EXAMPLE.COM;
defaulting to no policy
Principal "host/jupiter.example.com@EXAMPLE.COM" created.

Instead of setting a password for the new principal, the -randkey flag tells kadmin to generate a random key. This is used here because no user interaction is wanted for this principal. It is a server account for the machine.

Finally, extract the key and store it in the local keytab file /etc/krb5.keytab. This file is owned by the superuser, so you must be root to execute the next command in the kadmin shell:

kadmin:  ktadd host/jupiter.example.com
Entry for principal host/jupiter.example.com with kvno 3, encryption type Triple
DES cbc mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab.
Entry for principal host/jupiter.example.com with kvno 3, encryption type DES
cbc mode with CRC-32 added to keytab WRFILE:/etc/krb5.keytab.
kadmin:

When completed, make sure that you destroy the admin ticket obtained with kinit above with kdestroy.

6.4.9 Enabling PAM Support for Kerberos

Warning
Warning: Incomplete Configuration Locks Users Out

An incomplete Kerberos configuration may completely lock you out of your system, including the root user. To prevent this, add the ignore_unknown_principals directive to the pam_krb5 module after you have added the pam_krb5 module to the existing PAM configuration files as described below.

tux > sudo pam-config --add --krb5-ignore_unknown_principals

This will direct the pam_krb5 module to ignore some errors that would otherwise cause the account phase to fail.

SUSE® Linux Enterprise Server comes with a PAM module named pam_krb5, which supports Kerberos login and password update. This module can be used by applications such as console login, su, and graphical login applications like GDM. That is, it can be used in all cases where the user enters a password and expects the authenticating application to obtain an initial Kerberos ticket on their behalf. To configure PAM support for Kerberos, use the following command:

tux > sudo pam-config --add --krb5

The above command adds the pam_krb5 module to the existing PAM configuration files and makes sure it is called in the right order. To make precise adjustments to the way in which pam_krb5 is used, edit the file /etc/krb5.conf and add default applications to PAM. For details, refer to the manual page with man 5 pam_krb5.

The pam_krb5 module was specifically not designed for network services that accept Kerberos tickets as part of user authentication. This is an entirely different matter, and is discussed below.

6.4.10 Configuring SSH for Kerberos Authentication

OpenSSH supports Kerberos authentication in both protocol version 1 and 2. In version 1, there are special protocol messages to transmit Kerberos tickets. Version 2 does not use Kerberos directly anymore, but relies on GSSAPI, the General Security Services API. This is a programming interface that is not specific to Kerberos—it was designed to hide the peculiarities of the underlying authentication system, be it Kerberos, a public-key authentication system like SPKM, or others. However, the included GSSAPI library only supports Kerberos.

To use sshd with Kerberos authentication, edit /etc/ssh/sshd_config and set the following options:

# These are for protocol version 1
#
# KerberosAuthentication yes
# KerberosTicketCleanup yes

# These are for version 2 - better to use this
GSSAPIAuthentication yes
GSSAPICleanupCredentials yes

Then restart your SSH daemon using sudo systemctl restart sshd.

To use Kerberos authentication with protocol version 2, enable it on the client side as well. Do this either in the systemwide configuration file /etc/ssh/ssh_config or on a per-user level by editing ~/.ssh/config. In both cases, add the option GSSAPIAuthentication yes.

You should now be able to connect using Kerberos authentication. Use klist to verify that you have a valid ticket, then connect to the SSH server. To force SSH protocol version 1, specify the -1 option on the command line.

Tip
Tip: Additional Information

The file /usr/share/doc/packages/openssh/README.kerberos discusses the interaction of OpenSSH and Kerberos in more detail.

Tip
Tip: Additional Directives for Protocol Version 2

The GSSAPIKeyExchange mechanism (RFC 4462) is supported. This directive specifies how host keys are exchanged. For more information, see the sshd_config manual page (man sshd_config).

6.4.11 Using LDAP and Kerberos

When using Kerberos, one way to distribute the user information (such as user ID, groups, and home directory) in your local network is to use LDAP. This requires a strong authentication mechanism that prevents packet spoofing and other attacks. One solution is to use Kerberos for LDAP communication, too.

OpenLDAP implements most authentication flavors through SASL, the simple authentication session layer. SASL is a network protocol designed for authentication. The SASL implementation is cyrus-sasl, which supports several authentication flavors. Kerberos authentication is performed through GSSAPI (General Security Services API). By default, the SASL plug-in for GSSAPI is not installed. Install the cyrus-sasl-gssapi with YaST.

To enable Kerberos to bind to the OpenLDAP server, create a principal ldap/ldap.example.com and add that to the keytab.

By default, the LDAP server slapd runs as user and group ldap, while the keytab file is readable by root only. Therefore, either change the LDAP configuration so the server runs as root or make the keytab file readable by the group ldap. The latter is done automatically by the OpenLDAP start script (/usr/lib/openldap/start) if the keytab file has been specified in the OPENLDAP_KRB5_KEYTAB variable in /etc/sysconfig/openldap and the OPENLDAP_CHOWN_DIRS variable is set to yes, which is the default setting. If OPENLDAP_KRB5_KEYTAB is left empty, the default keytab under /etc/krb5.keytab is used and you must adjust the privileges yourself as described below.

To run slapd as root, edit /etc/sysconfig/openldap. Disable the OPENLDAP_USER and OPENLDAP_GROUP variables by putting a comment character in front of them.

To make the keytab file readable by group LDAP, execute

chgrp ldap /etc/krb5.keytab
chmod 640 /etc/krb5.keytab

A third (and maybe the best) solution is to tell OpenLDAP to use a special keytab file. To do this, start kadmin, and enter the following command after you have added the principal ldap/ldap.example.com:

ktadd -k /etc/openldap/ldap.keytab ldap/ldap.example.com@EXAMPLE.COM

Then in the shell run:

chown ldap.ldap /etc/openldap/ldap.keytab
chmod 600 /etc/openldap/ldap.keytab

To tell OpenLDAP to use a different keytab file, change the following variable in /etc/sysconfig/openldap:

OPENLDAP_KRB5_KEYTAB="/etc/openldap/ldap.keytab"

Finally, restart the LDAP server using sudo systemctl restart slapd.

6.4.11.1 Using Kerberos Authentication with LDAP

You are now able to automatically use tools such as ldapsearch with Kerberos authentication.

ldapsearch -b ou=people,dc=example,dc=com '(uid=geeko)'

SASL/GSSAPI authentication started
SASL SSF: 56
SASL installing layers
[...]

# geeko, people, example.com
dn: uid=geeko,ou=people,dc=example,dc=com
uid: geeko
cn: Suzanne Geeko
[...]

As you can see, ldapsearch prints a message that it started GSSAPI authentication. The next message is very cryptic, but it shows that the security strength factor (SSF for short) is 56 (The value 56 is somewhat arbitrary. Most likely it was chosen because this is the number of bits in a DES encryption key). This means that GSSAPI authentication was successful and that encryption is being used to protect integrity and provide confidentiality for the LDAP connection.

In Kerberos, authentication is always mutual. This means that not only have you authenticated yourself to the LDAP server, but also the LDAP server has authenticated itself to you. In particular, this means communication is with the desired LDAP server, rather than some bogus service set up by an attacker.

6.4.11.2 Kerberos Authentication and LDAP Access Control

There is one minor piece of the puzzle missing—how the LDAP server can find out that the Kerberos user tux@EXAMPLE.COM corresponds to the LDAP distinguished name uid=tux,ou=people,dc=example,dc=com. This sort of mapping must be configured manually using the saslExpr directive. In this example, the "authz-regexp" change in LDIF would look as follows:

dn: cn=config
add: olcAuthzRegexp
olcAuthzRegexp: uid=(.*),cn=GSSAPI,cn=auth uid=$1,ou=people,dc=example,dc=com

All these changes can be applied via ldapmodify on the command line.

When SASL authenticates a user, OpenLDAP forms a distinguished name from the name given to it by SASL (such as tux) and the name of the SASL flavor (GSSAPI). The result would be uid=tux,cn=GSSAPI,cn=auth.

If a authz-regexp has been configured, it checks the DN formed from the SASL information using the first argument as a regular expression. If this regular expression matches, the name is replaced with the second argument of the authz-regexp statement. The placeholder $1 is replaced with the substring matched by the (.*) expression.

More complicated match expressions are possible. If you have a more complicated directory structure or a schema in which the user name is not part of the DN, you can even use search expressions to map the SASL DN to the user DN.

For more information, see the slapd-config man page.

6.5 Setting up Kerberos using LDAP and Kerberos Client

YaST includes the module LDAP and Kerberos Client that helps define authentication scenarios involving either LDAP or Kerberos.

It can also be used to join Kerberos and LDAP separately. However, in many such cases, using this module may not be the first choice, such as for joining Active Directory (which uses a combination of LDAP and Kerberos). For more information, see Section 4.2, “Configuring an Authentication Client with YaST”.

Start the module by selecting Network Services › LDAP and Kerberos Client.

LDAP and Kerberos Client Window
Figure 6.2: LDAP and Kerberos Client Window

To configure a Kerberos client, follow the procedure below:

  1. In the window LDAP and Kerberos Client, click Change Settings.

    Choose the tab Authentication via Kerberos.

    Tab Authentication via Kerberos
  2. Click Add Realm.

  3. In the appearing dialog, specify the correct Realm name. Usually, the realm name is an uppercase version of the domain name. Additionally, you can specify the following:

    • To apply mappings from the realm name to the domain name, activate Map Domain Name to the Realm and/or Map Wildcard Domain Name to the Realm.

    • You can specify the Host Name of Administration Server, the Host Name of Master Key Distribution Server and additional Key Distribution Centers.

      All of these items are optional if they can be automatically discovered via the SRV and TXT records in DNS.

    • To manually map Principals to local user names, use Custom Mappings of Principal Names to User Names.

      You can also use auth_to_local rules to supply such mappings using Custom Rules for Mapping Principal Names to User Names. For more information about using such rules, see the official documentation at https://web.mit.edu/kerberos/krb5-current/doc/admin/conf_files/krb5_conf.html#realms.

    Continue with OK.

  4. To add more realms, repeat from Step 2.

  5. Enable Kerberos users logging in and creation of home directories by activating Allow Kerberos Users to Authenticate and Automatically Create Home Directory.

  6. If you left empty the optional text boxes in Step 3, make sure to enable automatic discovery of realms and key distribution centers by activating Use DNS TXT Record to Discover Realms and Use DNS SRV Record to Discover KDC Servers.

  7. You can additionally activate the following:

    • Allow Insecure Encryption (for Windows NT) allows the encryption types listed as weak at http://web.mit.edu/kerberos/krb5-current/doc/admin/conf_files/kdc_conf.html#encryption-types.

    • Allow KDC on Other Networks to Issue Authentication Tickets allows forwarding of tickets.

    • Allow Kerberos-Enabled Services to Take on The Identity Of a User allows the use of proxies between the computer of the user and the key distribution center.

    • Issue Address-Less Tickets for Computers Behind NAT allows granting tickets to users behind networks using network address translation.

  8. To set up allowed encryption types and define the name of the keytab file which lists the names of principals and their encrypted keys, use the Extended Options.

  9. Finish with OK and Finish.

    YaST may now install extra packages.

6.6 For More Information

The official site of MIT Kerberos is http://web.mit.edu/kerberos. There, find links to any other relevant resource concerning Kerberos, including Kerberos installation, user, and administration guides.

The book Kerberos—A Network Authentication System by Brian Tung (ISBN 0-201-37924-4) offers extensive information.

7 Active Directory Support

  • Filename: security_ad_support.xml
  • ID: cha.security.ad

Active Directory* (AD) is a directory-service based on LDAP, Kerberos, and other services. It is used by Microsoft* Windows* to manage resources, services, and people. In a Microsoft Windows network, Active Directory provides information about these objects, restricts access to them, and enforces policies. SUSE® Linux Enterprise Server lets you join existing Active Directory domains and integrate your Linux machine into a Windows environment.

7.1 Integrating Linux and Active Directory Environments

With a Linux client (configured as an Active Directory client) that is joined to an existing Active Directory domain, benefit from various features not available on a pure SUSE Linux Enterprise Server Linux client:

Browsing Shared Files and Directories with SMB

GNOME Files (previously called Nautilus) supports browsing shared resources through SMB.

Sharing Files and Directories with SMB

GNOME Files supports sharing directories and files as in Windows.

Accessing and Manipulating User Data on the Windows Server

Through GNOME Files, users can access their Windows user data and can edit, create, and delete files and directories on the Windows server. Users can access their data without having to enter their password multiple times.

Offline Authentication

Users can log in and access their local data on the Linux machine even if they are offline or the Active Directory server is unavailable for other reasons.

Windows Password Change

This port of Active Directory support in Linux enforces corporate password policies stored in Active Directory. The display managers and console support password change messages and accept your input. You can even use the Linux passwd command to set Windows passwords.

Single-Sign-On through Kerberized Applications

Many desktop applications are Kerberos-enabled (kerberized), which means they can transparently handle authentication for the user without the need for password reentry at Web servers, proxies, groupware applications, or other locations.

Note
Note: Managing Unix Attributes from Windows Server* 2016 and Later

In Windows Server 2016 and later, Microsoft has removed the role IDMU/NIS Server and along with it the Unix Attributes plug-in for the Active Directory Users and Computers MMC snap-in.

However, Unix attributes can still be managed manually when Advanced Options are enabled in the Active Directory Users and Computers MMC snap-in. For more information, see https://blogs.technet.microsoft.com/activedirectoryua/2016/02/09/identity-management-for-unix-idmu-is-deprecated-in-windows-server/.

Alternatively, use the method described in Procedure 7.1, “ Joining an Active Directory Domain Using User Logon Management to complete attributes on the client side (in particular, see Step 6.c).

The following section contains technical background for most of the previously named features.

7.2 Background Information for Linux Active Directory Support

Many system components need to interact flawlessly to integrate a Linux client into an existing Windows Active Directory domain. The following sections focus on the underlying processes of the key events in Active Directory server and client interaction.

To communicate with the directory service, the client needs to share at least two protocols with the server:

LDAP

LDAP is a protocol optimized for managing directory information. A Windows domain controller with Active Directory can use the LDAP protocol to exchange directory information with the clients. To learn more about LDAP in general and about the open source port of it, OpenLDAP, refer to Chapter 5, LDAP—A Directory Service.

Kerberos

Kerberos is a third-party trusted authentication service. All its clients trust Kerberos's authorization of another client's identity, enabling kerberized single-sign-on (SSO) solutions. Windows supports a Kerberos implementation, making Kerberos SSO possible even with Linux clients. To learn more about Kerberos in Linux, refer to Chapter 6, Network Authentication with Kerberos.

Depending on which YaST module you use to set up Kerberos authentication, different client components process account and authentication data:

Solutions Based on SSSD
  • The sssd daemon is the central part of this solution. It handles all communication with the Active Directory server.

  • To gather name service information, sssd_nss is used.

  • To authenticate users, the pam_sss module for PAM is used. The creation of user homes for the Active Directory users on the Linux client is handled by pam_mkhomedir.

    For more information about PAM, see Chapter 2, Authentication with PAM.

Solution Based On Winbind (Samba)
  • The winbindd daemon is the central part of this solution. It handles all communication with the Active Directory server.

  • To gather name service information, nss_winbind is used.

  • To authenticate users, the pam_winbind module for PAM is used. The creation of user homes for the Active Directory users on the Linux client is handled by pam_mkhomedir.

    For more information about PAM, see Chapter 2, Authentication with PAM.

Figure 7.1, “Schema of Winbind-based Active Directory Authentication” highlights the most prominent components of Winbind-based Active Directory authentication.

Schema of Winbind-based Active Directory Authentication
Figure 7.1: Schema of Winbind-based Active Directory Authentication

Applications that are PAM-aware, like the login routines and the GNOME display manager, interact with the PAM and NSS layer to authenticate against the Windows server. Applications supporting Kerberos authentication (such as file managers, Web browsers, or e-mail clients) use the Kerberos credential cache to access user's Kerberos tickets, making them part of the SSO framework.

7.2.1 Domain Join

During domain join, the server and the client establish a secure relation. On the client, the following tasks need to be performed to join the existing LDAP and Kerberos SSO environment provided by the Windows domain controller. The entire join process is handled by the YaST Domain Membership module, which can be run during installation or in the installed system:

  1. The Windows domain controller providing both LDAP and KDC (Key Distribution Center) services is located.

  2. A machine account for the joining client is created in the directory service.

  3. An initial ticket granting ticket (TGT) is obtained for the client and stored in its local Kerberos credential cache. The client needs this TGT to get further tickets allowing it to contact other services, like contacting the directory server for LDAP queries.

  4. NSS and PAM configurations are adjusted to enable the client to authenticate against the domain controller.

During client boot, the winbind daemon is started and retrieves the initial Kerberos ticket for the machine account. winbindd automatically refreshes the machine's ticket to keep it valid. To keep track of the current account policies, winbindd periodically queries the domain controller.

7.2.2 Domain Login and User Homes

The login manager of GNOME (GDM) has been extended to allow the handling of Active Directory domain login. Users can choose to log in to the primary domain the machine has joined or to one of the trusted domains with which the domain controller of the primary domain has established a trust relationship.

User authentication is mediated by several PAM modules as described in Section 7.2, “Background Information for Linux Active Directory Support”. If there are errors, the error codes are translated into user-readable error messages that PAM gives at login through any of the supported methods (GDM, console, and SSH):

Password has expired

The user sees a message stating that the password has expired and needs to be changed. The system prompts for a new password and informs the user if the new password does not comply with corporate password policies (for example the password is too short, too simple, or already in the history). If a user's password change fails, the reason is shown and a new password prompt is given.

Account disabled

The user sees an error message stating that the account has been disabled and to contact the system administrator.

Account locked out

The user sees an error message stating that the account has been locked and to contact the system administrator.

Password has to be changed

The user can log in but receives a warning that the password needs to be changed soon. This warning is sent three days before that password expires. After expiration, the user cannot log in.

Invalid workstation

When a user is restricted to specific workstations and the current SUSE Linux Enterprise Server machine is not among them, a message appears that this user cannot log in from this workstation.

Invalid logon hours

When a user is only allowed to log in during working hours and tries to log in outside working hours, a message informs the user that logging in is not possible at that time.

Account expired

An administrator can set an expiration time for a specific user account. If that user tries to log in after expiration, the user gets a message that the account has expired and cannot be used to log in.

During a successful authentication, the client acquires a ticket granting ticket (TGT) from the Kerberos server of Active Directory and stores it in the user's credential cache. It also renews the TGT in the background, requiring no user interaction.

SUSE Linux Enterprise Server supports local home directories for Active Directory users. If configured through YaST as described in Section 7.3, “Configuring a Linux Client for Active Directory”, user home directories are created when a Windows/Active Directory user first logs in to the Linux client. These home directories look and feel identical to standard Linux user home directories and work independently of the Active Directory Domain Controller.

Using a local user home, it is possible to access a user's data on this machine (even when the Active Directory server is disconnected) as long as the Linux client has been configured to perform offline authentication.

7.2.3 Offline Service and Policy Support

Users in a corporate environment must have the ability to become roaming users (for example, to switch networks or even work disconnected for some time). To enable users to log in to a disconnected machine, extensive caching was integrated into the winbind daemon. The winbind daemon enforces password policies even in the offline state. It tracks the number of failed login attempts and reacts according to the policies configured in Active Directory. Offline support is disabled by default and must be explicitly enabled in the YaST Domain Membership module.

When the domain controller has become unavailable, the user can still access network resources (other than the Active Directory server itself) with valid Kerberos tickets that have been acquired before losing the connection (as in Windows). Password changes cannot be processed unless the domain controller is online. While disconnected from the Active Directory server, a user cannot access any data stored on this server. When a workstation has become disconnected from the network entirely and connects to the corporate network again later, SUSE Linux Enterprise Server acquires a new Kerberos ticket when the user has locked and unlocked the desktop (for example, using a desktop screen saver).

7.3 Configuring a Linux Client for Active Directory

Before your client can join an Active Directory domain, some adjustments must be made to your network setup to ensure the flawless interaction of client and server.

DNS

Configure your client machine to use a DNS server that can forward DNS requests to the Active Directory DNS server. Alternatively, configure your machine to use the Active Directory DNS server as the name service data source.

NTP

To succeed with Kerberos authentication, the client must have its time set accurately. It is highly recommended to use a central NTP time server for this purpose (this can be also the NTP server running on your Active Directory domain controller). If the clock skew between your Linux host and the domain controller exceeds a certain limit, Kerberos authentication fails and the client is logged in using the weaker NTLM (NT LAN Manager) authentication. For more details about using Active Directory for time synchronization, see Procedure 7.2, “ Joining an Active Directory Domain Using Windows Domain Membership.

Firewall

To browse your network neighborhood, either disable the firewall entirely or mark the interface used for browsing as part of the internal zone.

To change the firewall settings on your client, log in as root and start the YaST firewall module. Select Interfaces. Select your network interface from the list of interfaces and click Change. Select Internal Zone and apply your settings with OK. Leave the firewall settings with Next › Finish. To disable the firewall, check the Disable Firewall Automatic Starting option, and leave the firewall module with Next › Finish.

Active Directory Account

You cannot log in to an Active Directory domain unless the Active Directory administrator has provided you with a valid user account for that domain. Use the Active Directory user name and password to log in to the Active Directory domain from your Linux client.

7.3.1 Choosing Which YaST Module to Use for Connecting to Active Directory

YaST contains multiple modules that allow connecting to an Active Directory:

7.3.2 Joining Active Directory Using User Logon Management

The YaST module User Logon Management supports authentication at an Active Directory. Additionally, it also supports the following related authentication and identification providers:

Identification Providers
  • Delegate to third-party software library Support for legacy NSS providers via a proxy.

  • FreeIPA FreeIPA and Red Hat Enterprise Identity Management provider.

  • Generic directory service (LDAP) An LDAP provider. For more information about configuring LDAP, see man 5 sssd-ldap.

  • Local SSSD file database An SSSD-internal provider for local users.

Authentication Providers
  • Delegate to third-party software library Relay authentication to another PAM target via a proxy.

  • FreeIPA FreeIPA and Red Hat Enterprise Identity Management provider.

  • Generic Kerberos service An LDAP provider.

  • Generic directory service (LDAP) Kerberos authentication.

  • Local SSSD file database An SSSD-internal provider for local users.

  • This domain does not provide authentication service Disables authentication explicitly.

To join an Active Directory domain using SSSD and the User Logon Management module of YaST, proceed as follows:

Procedure 7.1: Joining an Active Directory Domain Using User Logon Management
  1. Open YaST.

  2. To be able to use DNS auto-discovery later, set up the Active Directory Domain Controller (the Active Directory server) as the name server for your client.

    1. In YaST, click Network Settings.

    2. Select Hostname/DNS, then enter the IP address of the Active Directory Domain Controller into the text box Name Server 1.

      Save the setting with OK.

  3. From the YaST main window, start the module User Logon Management.

    The module opens with an overview showing different network properties of your computer and the authentication method currently in use.

    Overview window showing the computer name, IP address, and its authentication setting.
    Figure 7.2: Main Window of User Logon Management
  4. To start editing, click Change Settings.

  5. Now join the domain.

    1. Click Join Domain.

    2. In the appearing dialog, specify the correct Domain name. Then specify the services to use for identity data and authentication: Select Microsoft Active Directory for both.

      Ensure that Enable the domain is activated.

      Click OK.

    3. (Optional) Usually, you can keep the default settings in the following dialog. However, there are reasons to make changes:

      • If the Local Host Name Does Not Match the Host Name Set on the Domain Controller.  Find out if the host name of your computer matches what the name your computer is known as to the Active Directory Domain Controller. In a terminal, run the command hostname, then compare its output to the configuration of the Active Directory Domain Controller.

        If the values differ, specify the host name from the Active Directory configuration under AD hostname. Otherwise, leave the appropriate text box empty.

      • If You Do Not Want to Use DNS Auto-Discovery.  Specify the Host names of Active Directory servers that you want to use. If there are multiple Domain Controllers, separate their host names with commas.

    4. To continue, click OK.

      If not all software is installed already, the computer will now install missing software. It will then check whether the configured Active Directory Domain Controller is available.

    5. If everything is correct, the following dialog should now show that it has discovered an Active Directory Server but that you are Not yet enrolled.

      In the dialog, specify the Username and Password of the Active Directory administrator account (usually Administrator).

      To make sure that the current domain is enabled for Samba, activate Overwrite Samba configuration to work with this AD.

      To enroll, click OK.

      Enrolling into a Domain
      Figure 7.3: Enrolling into a Domain
    6. You should now see a message confirming that you have enrolled successfully. Finish with OK.

  6. After enrolling, configure the client using the window Manage Domain User Logon.

    Configuration Window of User Logon Management
    Figure 7.4: Configuration Window of User Logon Management
    1. To allow logging in to the computer using login data provided by Active Directory, activate Allow Domain User Logon.

    2. (Optional) Optionally, under Enable domain data source, activate additional data sources such as information on which users are allowed to use sudo or which network drives are available.

    3. To allow Active Directory users to have home directories, activate Create Home Directories. The path for home directories can be set in multiple ways—on the client, on the server, or both ways:

      • To configure the home directory paths on the Domain Controller, set an appropriate value for the attribute UnixHomeDirectory for each user. Additionally, make sure that this attribute replicated to the global catalog. For information on achieving that under Windows, see https://support.microsoft.com/en-us/kb/248717.

      • To configure home directory paths on the client in such a way that precedence will be given to the path set on the domain controller, use the option fallback_homedir.

      • To configure home directory paths on the client in such a way that the client setting will override the server setting, use override_homedir.

      As settings on the Domain Controller are outside of the scope of this documentation, only the configuration of the client-side options will be described in the following.

      From the side bar, select Service Options › Name switch, then click Extended Options. From that window, select either fallback_homedir or override_homedir, then click Add.

      Specify a value. To have home directories follow the format /home/USER_NAME, use /home/%u. For more information about possible variables, see the man page sssd.conf (man 5 sssd.conf), section override_homedir.

      Click OK.

  7. Save the changes by clicking OK. Then make sure that the values displayed now are correct. To leave the dialog, click Cancel.

7.3.3 Joining Active Directory Using Windows Domain Membership

To join an Active Directory domain using winbind and the Windows Domain Membership module of YaST, proceed as follows:

Procedure 7.2: Joining an Active Directory Domain Using Windows Domain Membership
  1. Log in as root and start YaST.

  2. Start Network Services › Windows Domain Membership.

  3. Enter the domain to join at Domain or Workgroup in the Windows Domain Membership screen (see Figure 7.5, “Determining Windows Domain Membership”). If the DNS settings on your host are properly integrated with the Windows DNS server, enter the Active Directory domain name in its DNS format (mydomain.mycompany.com). If you enter the short name of your domain (also known as the pre–Windows 2000 domain name), YaST must rely on NetBIOS name resolution instead of DNS to find the correct domain controller.

    Determining Windows Domain Membership
    Figure 7.5: Determining Windows Domain Membership
  4. To use the SMB source for Linux authentication, activate Also Use SMB Information for Linux Authentication.

  5. To automatically create a local home directory for Active Directory users on the Linux machine, activate Create Home Directory on Login.

  6. Check Offline Authentication to allow your domain users to log in even if the Active Directory server is temporarily unavailable, or if you do not have a network connection.

  7. To change the UID and GID ranges for the Samba users and groups, select Expert Settings. Let DHCP retrieve the WINS server only if you need it. This is the case when some machines are resolved only by the WINS system.

  8. Configure NTP time synchronization for your Active Directory environment by selecting NTP Configuration and entering an appropriate server name or IP address. This step is obsolete if you have already entered the appropriate settings in the stand-alone YaST NTP configuration module.

  9. Click OK and confirm the domain join when prompted for it.

  10. Provide the password for the Windows administrator on the Active Directory server and click OK (see Figure 7.6, “Providing Administrator Credentials”).

    Providing Administrator Credentials
    Figure 7.6: Providing Administrator Credentials

After you have joined the Active Directory domain, you can log in to it from your workstation using the display manager of your desktop or the console.

Important
Important: Domain Name

Joining a domain may not succeed if the domain name ends with .local. Names ending in .local cause conflicts with Multicast DNS (MDNS) where .local is reserved for link-local host names.

Note
Note: Only Administrators Can Enroll a Computer

Only a domain administrator account, such as Administrator, can join SUSE Linux Enterprise Server into Active Directory.

7.3.4 Checking Active Directory Connection Status

To check whether you are successfully enrolled in an Active Directory domain, use the following commands:

  • klist shows whether the current user has a valid Kerberos ticket.

  • getent passwd shows published LDAP data for all users.

7.4 Logging In to an Active Directory Domain

Provided your machine has been configured to authenticate against Active Directory and you have a valid Windows user identity, you can log in to your machine using the Active Directory credentials. Login is supported for GNOME, the console, SSH, and any other PAM-aware application.

Important
Important: Offline Authentication

SUSE Linux Enterprise Server supports offline authentication, allowing you to log in to your client machine even when it is offline. See Section 7.2.3, “Offline Service and Policy Support” for details.

7.4.1 GDM

To authenticate a GNOME client machine against an Active Directory server, proceed as follows:

  1. Click Not listed.

  2. In the text box Username, enter the domain name and the Windows user name in this form: DOMAIN_NAME\USER_NAME.

  3. Enter your Windows password.

If configured to do so, SUSE Linux Enterprise Server creates a user home directory on the local machine on the first login of each user authenticated via Active Directory. This allows you to benefit from the Active Directory support of SUSE Linux Enterprise Server while still having a fully functional Linux machine at your disposal.

7.4.2 Console Login

Besides logging in to the Active Directory client machine using a graphical front-end, you can log in using the text-based console or even remotely using SSH.

To log in to your Active Directory client from a console, enter DOMAIN_NAME\USER_NAME at the login: prompt and provide the password.

To remotely log in to your Active Directory client machine using SSH, proceed as follows:

  1. At the login prompt, enter:

    ssh DOMAIN_NAME\\USER_NAME@HOST_NAME

    The \ domain and login delimiter is escaped with another \ sign.

  2. Provide the user's password.

7.5 Changing Passwords

SUSE Linux Enterprise Server helps the user choose a suitable new password that meets the corporate security policy. The underlying PAM module retrieves the current password policy settings from the domain controller, informing the user about the specific password quality requirements a user account typically has by means of a message on login. Like its Windows counterpart, SUSE Linux Enterprise Server presents a message describing:

  • Password history settings

  • Minimum password length requirements

  • Minimum password age

  • Password complexity

The password change process cannot succeed unless all requirements have been successfully met. Feedback about the password status is given both through the display managers and the console.

GDM provides feedback about password expiration and the prompt for new passwords in an interactive mode. To change passwords in the display managers, provide the password information when prompted.

To change your Windows password, you can use the standard Linux utility, passwd, instead of having to manipulate this data on the server. To change your Windows password, proceed as follows:

  1. Log in at the console.

  2. Enter passwd.

  3. Enter your current password when prompted.

  4. Enter the new password.

  5. Reenter the new password for confirmation. If your new password does not comply with the policies on the Windows server, this feedback is given to you and you are prompted for another password.

To change your Windows password from the GNOME desktop, proceed as follows:

  1. Click the Computer icon on the left edge of the panel.

  2. Select Control Center.

  3. From the Personal section, select About Me › Change Password.

  4. Enter your old password.

  5. Enter and confirm the new password.

  6. Leave the dialog with Close to apply your settings.

Part II Local Security

8 Configuring Security Settings with YaST

The YaST module Security Center and Hardening offers a central clearinghouse to configure security-related settings for SUSE Linux Enterprise Server. Use it to configure security aspects such as settings for the login procedure and for password creation, for boot permissions, user creation or for default file permissions. Launch it from the YaST control center by Security and Users › Security Center and Hardening. The Security Center dialog always starts with the Security Overview, and other configuration dialogs are available from the right pane.

9 Authorization with PolKit

PolKit (formerly known as PolicyKit) is an application framework that acts as a negotiator between the unprivileged user session and the privileged system context. Whenever a process from the user session tries to carry out an action in the system context, PolKit is queried. Based on its configuration—specified in a so-called policy—the answer could be yes, no, or needs authentication. Unlike classical privilege authorization programs such as sudo, PolKit does not grant root permissions to an entire session, but only to the action in question.

10 Access Control Lists in Linux

POSIX ACLs (access control lists) can be used as an expansion of the traditional permission concept for file system objects. With ACLs, permissions can be defined more flexibly than with the traditional permission concept.

11 Encrypting Partitions and Files

Encrypting files, partitions, and entire disks prevents unauthorized access to your data and protects your confidential files and documents.

12 Certificate Store

Certificates play an important role in the authentication of companies and individuals. Usually certificates are administered by the application itself. In some cases, it makes sense to share certificates between applications. The certificate store is a common ground for Firefox, Evolution, and NetworkManager. This chapter explains some details.

13 Intrusion Detection with AIDE

Securing your systems is a mandatory task for any mission-critical system administrator. Because it is impossible to always guarantee that the system is not compromised, it is very important to do extra checks regularly (for example with cron) to ensure that the system is still under your control. This is where AIDE, the Advanced Intrusion Detection Environment, comes into play.

8 Configuring Security Settings with YaST

  • Filename: security_yast2_security.xml
  • ID: cha.security.yast_security
Abstract

The YaST module Security Center and Hardening offers a central clearinghouse to configure security-related settings for SUSE Linux Enterprise Server. Use it to configure security aspects such as settings for the login procedure and for password creation, for boot permissions, user creation or for default file permissions. Launch it from the YaST control center by Security and Users › Security Center and Hardening. The Security Center dialog always starts with the Security Overview, and other configuration dialogs are available from the right pane.

8.1 Security Overview

The Security Overview displays a comprehensive list of the most important security settings for your system. The security status of each entry in the list is clearly visible. A green check mark indicates a secure setting while a red cross indicates an entry as being insecure. Click Help to open an overview of the setting and information on how to make it secure. To change a setting, click the corresponding link in the Status column. Depending on the setting, the following entries are available:

Enabled/Disabled

Click this entry to toggle the status of the setting to either enabled or disabled.

Configure

Click this entry to launch another YaST module for configuration. You will return to the Security Overview when leaving the module.

Unknown

A setting's status is set to unknown when the associated service is not installed. Such a setting does not represent a potential security risk.

YaST Security Center and Hardening: Security Overview
Figure 8.1: YaST Security Center and Hardening: Security Overview

8.2 Predefined Security Configurations

SUSE Linux Enterprise Server comes with three Predefined Security Configurations. These configurations affect all the settings available in the Security Center module. Each configuration can be modified to your needs using the dialogs available from the right pane changing its state to Custom Settings:

Workstation

A configuration for a workstation with any kind of network connection (including a connection to the Internet).

Roaming Device

This setting is designed for a laptop or tablet that connects to different networks.

Network Server

Security settings designed for a machine providing network services such as a Web server, file server, name server, etc. This set provides the most secure configuration of the predefined settings.

Custom Settings

A pre-selected Custom Settings (when opening the Predefined Security Configurations dialog) indicates that one of the predefined sets has been modified. Actively choosing this option does not change the current configuration—you will need to change it using the Security Overview.

8.3 Password Settings

Passwords that are easy to guess are a major security issue. The Password Settings dialog provides the means to ensure that only secure passwords can be used.

Check New Passwords

By activating this option, a warning will be issued if new passwords appear in a dictionary, or if they are proper names (proper nouns).

Minimum Acceptable Password Length

If the user chooses a password with a length shorter than specified here, a warning will be issued.

Number of Passwords to Remember

When password expiration is activated (via Password Age), this setting stores the given number of a user's previous passwords, preventing their reuse.

Password Encryption Method

Choose a password encryption algorithm. Normally there is no need to change the default (Blowfish).

Password Age

Activate password expiration by specifying a minimum and a maximum time limit (in days). By setting the minimum age to a value greater than 0 days, you can prevent users from immediately changing their passwords again (and in doing so circumventing the password expiration). Use the values 0 and 99999 to deactivate password expiration.

Days Before Password Expires Warning

When a password expires, the user receives a warning in advance. Specify the number of days prior to the expiration date that the warning should be issued.

8.4 Boot Settings

Configure which users can shut down the machine via the graphical login manager in this dialog. You can also specify how CtrlAltDel will be interpreted and who can hibernate the system.

8.5 Login Settings

This dialog lets you configure security-related login settings:

Delay after Incorrect Login Attempt

To make it difficult to guess a user's password by repeatedly logging in, it is recommended to delay the display of the login prompt that follows an incorrect login. Specify the value in seconds. Make sure that users who have mistyped their passwords do not need to wait too long.

Allow Remote Graphical Login

When checked, the graphical login manager (GDM) can be accessed from the network. This is a potential security risk.

8.6 User Addition

Set minimum and maximum values for user and group IDs. These default settings would rarely need to be changed.

8.7 Miscellaneous Settings

Other security settings that do not fit the above-mentioned categories are listed here:

File Permissions

SUSE Linux Enterprise Server comes with three predefined sets of file permissions for system files. These permission sets define whether a regular user may read log files or start certain programs. Easy file permissions are suitable for stand-alone machines. These settings allow regular users to, for example, read most system files. See the file /etc/permissions.easy for the complete configuration. The Secure file permissions are designed for multiuser machines with network access. A thorough explanation of these settings can be found in /etc/permissions.secure. The Paranoid settings are the most restrictive ones and should be used with care. See /etc/permissions.paranoid for more information.

User Launching updatedb

The program updatedb scans the system and creates a database of all file locations which can be queried with the command locate. When updatedb is run as user nobody, only world-readable files will be added to the database. When run as user root, almost all files (except the ones root is not allowed to read) will be added.

Enable Magic SysRq Keys

The magic SysRq key is a key combination that enables you to have some control over the system even when it has crashed. The complete documentation can be found at https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html.

9 Authorization with PolKit

  • Filename: security_policy_kit.xml
  • ID: cha.security.policykit
Abstract

PolKit (formerly known as PolicyKit) is an application framework that acts as a negotiator between the unprivileged user session and the privileged system context. Whenever a process from the user session tries to carry out an action in the system context, PolKit is queried. Based on its configuration—specified in a so-called policy—the answer could be yes, no, or needs authentication. Unlike classical privilege authorization programs such as sudo, PolKit does not grant root permissions to an entire session, but only to the action in question.

9.1 Conceptual Overview

PolKit works by limiting specific actions by users, by group, or by name. It then defines how those users are allowed to perform this action.

9.1.1 Available Authentication Agents

When a user starts a session (using the graphical environment or on the console), each session consists of the authority and an authentication agent. The authority is implemented as a service on the system message bus, whereas the authentication agent is used to authenticate the current user, which started the session. The current user needs to prove their authenticity, for example, using a passphrase.

Each desktop environment has its own authentication agent. Usually it is started automatically, whatever environment you choose.

9.1.2 Structure of PolKit

PolKit's configuration depends on actions and authorization rules:

Actions (file extension *.policy)

Written as XML files and located in /usr/share/polkit-1/actions. Each file defines one or more actions, and each action contains descriptions and default permissions. Although a system administrator can write their own rules, PolKit's files must not be edited.

Authorization Rules (file extension *.rules)

Written as JavaScript files and located in two places: /usr/share/polkit-1/rules.d is used for third party packages and /etc/polkit-1/rules.d for local configurations. Each rule file refers to the action specified in the action file. A rule determines what restrictions are allowed to a subset of users. For example, a rule file could overrule a restrictive permission and allow some users to allow it.

9.1.3 Available Commands

PolKit contains several commands for specific tasks (see also the specific man page for further details):

pkaction

Get details about a defined action. See Section 9.3, “Querying Privileges” for more information.

pkcheck

Checks whether a process is authorized, specified by either --process or --system-bus-name.

pkexec

Allows an authorized user to execute the specific program as another user.

pkttyagent

Starts a textual authentication agent. This agent is used if a desktop environment does not have its own authentication agent.

9.1.4 Available Policies and Supported Applications

At the moment, not all applications requiring privileges use PolKit. Find the most important policies available on SUSE® Linux Enterprise Server below, sorted into the categories where they are used.

PulseAudio
Set scheduling priorities for the PulseAudio daemon
CUPS
Add, remove, edit, enable or disable printers
GNOME
Modify system and mandatory values with GConf
Change the system time
libvirt
Manage and monitor local virtualized systems
PolKit
Read and change privileges for other users
Modify defaults
PackageKit
Update and remove packages
Change and refresh repositories
Install local files
Rollback
Import repository keys
Accepting EULAs
Setting the network proxy
System
Wake on LAN
Mount or unmount fixed, hotpluggable and encrypted devices
Eject and decrypt removable media
Enable or disable WLAN
Enable or disable Bluetooth
Device access
Stop, suspend, hibernate and restart the system
Undock a docking station
Change power-management settings
YaST
Register product
Change the system time and language

9.2 Authorization Types

Every time a PolKit-enabled process carries out a privileged operation, PolKit is asked whether this process is entitled to do so. PolKit answers according to the policy defined for this process. The answers can be yes, no, or authentication needed. By default, a policy contains implicit privileges, which automatically apply to all users. It is also possible to specify explicit privileges which apply to a specific user.

9.2.1 Implicit Privileges

Implicit privileges can be defined for any active and inactive sessions. An active session is the one in which you are currently working. It becomes inactive when you switch to another console for example. When setting implicit privileges to no, no user is authorized, whereas yes authorizes all users. However, usually it is useful to demand authentication.

A user can either authorize by authenticating as root or by authenticating as self. Both authentication methods exist in four variants:

Authentication

The user always needs to authenticate.

One Shot Authentication

The authentication is bound to the instance of the program currently running. After the program is restarted, the user is required to authenticate again.

Keep Session Authentication

The authentication dialog offers a check button Remember authorization for this session. If checked, the authentication is valid until the user logs out.

Keep Indefinitely Authentication

The authentication dialog offers a check button Remember authorization. If checked, the user needs to authenticate only once.

9.2.2 Explicit Privileges

Explicit privileges can be granted to specific users. They can either be granted without limitations, or, when using constraints, limited to an active session and/or a local console.

It is not only possible to grant privileges to a user, a user can also be blocked. Blocked users cannot carry out an action requiring authorization, even though the default implicit policy allows authorization by authentication.

9.2.3 Default Privileges

Each application supporting PolKit comes with a default set of implicit policies defined by the application's developers. Those policies are the so-called upstream defaults. The privileges defined by the upstream defaults are not necessarily the ones that are activated by default on SUSE systems. SUSE Linux Enterprise Server comes with a predefined set of privileges that override the upstream defaults:

/etc/polkit-default-privs.standard

Defines privileges suitable for most desktop systems

/etc/polkit-default-privs.restrictive

Designed for machines administrated centrally. It is active by default.

To switch between the two sets of default privileges, adjust the value of POLKIT_DEFAULT_PRIVS to either restrictive or standard in /etc/sysconfig/security. Then run the command set_polkit_default_privs as root.

Do not modify the two files in the list above. To define your own custom set of privileges, use /etc/polkit-default-privs.local. For details, refer to Section 9.4.3, “Modifying Configuration Files for Implicit Privileges”.

9.3 Querying Privileges

To query privileges use the command pkaction included in PolKit.

PolKit comes with command line tools for changing privileges and executing commands as another user (see Section 9.1.3, “Available Commands” for a short overview). Each existing policy has a speaking, unique name with which it can be identified. List all available policies with the command pkaction.

When invoked with no parameters, the command pkaction lists all policies. By adding the --show-overrides option, you can list all policies that differ from the default values. To reset the privileges for a given action to the (upstream) defaults, use the option --reset-defaults ACTION. See man pkaction for more information.

If you want to display the needed authorization for a given policy (for example, org.freedesktop.login1.reboot) use pkaction as follows:

pkaction -v --action-id org.freedesktop.login1.reboot
org.freedesktop.login1.reboot:
  description:       Reboot the system
  message:           Authentication is required to allow rebooting the system
  vendor:            The systemd Project
  vendor_url:        http://www.freedesktop.org/wiki/Software/systemd
  icon:
  implicit any:      auth_admin_keep
  implicit inactive: auth_admin_keep
  implicit active:   yes

The keyword auth_admin_keep means that users need to enter a passphrase.

Note
Note: Restrictions of pkaction on SUSE Linux Enterprise Server

pkaction always operates on the upstream defaults. Therefore it cannot be used to list or restore the defaults shipped with SUSE Linux Enterprise Server. To do so, refer to Section 9.5, “Restoring the Default Privileges”.

9.4 Modifying Configuration Files

Adjusting privileges by modifying configuration files is useful when you want to deploy the same set of policies to different machines, for example to the computers of a specific team. It is possible to change implicit and explicit privileges by modifying configuration files.

9.4.1 Adding Action Rules

The available actions depend on what additional packages you have installed on your system. For a quick overview, use pkaction to list all defined rules.

To get an idea, the following example describes how the command gparted (GNOME Partition Editor) is integrated into PolKit.

The file /usr/share/polkit-1/actions/org.opensuse.policykit.gparted.policy contains the following content:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC
 "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
 "http://www.freedesktop.org/standards/PolicyKit/1.0/policyconfig.dtd">
<policyconfig> 1

  <action id="org.opensuse.policykit.gparted"> 2
    <message>Authentication is required to run the GParted Partition Editor</message>
    <icon_name>gparted</icon_name>
    <defaults> 3
      <allow_any>auth_admin</allow_any>
      <allow_inactive>auth_admin</allow_inactive>
     < allow_active>auth_admin</allow_active>
    </defaults>
    <annotate 4
      key="org.freedesktop.policykit.exec.path">/usr/sbin/gparted</annotate>
    <annotate 4
      key="org.freedesktop.policykit.exec.allow_gui">true</annotate>
  </action>

</policyconfig>

1

Root element of the policy file.

2

Contains one single action.

3

The defaults element contains several permissions used in remote sessions like SSH, VNC (element allow_inactive), when logged directly into the machine on a TTY or X display (element allow_active), or for both (element allow_any). The value auth_admin indicates authentication is required as an administrative user.

4

The annotate element contains specific information regarding how PolKit performs an action. In this case, it contains the path to the executable and states whether a GUI is allowed to open a X display.

To add your own policy, create a .policy file with the structure above, add the appropriate value into the id attribute, and define the default permissions.

9.4.2 Adding Authorization Rules

Your own authorization rules overrule the default settings. To add your own settings, store your files under /etc/polkit-1/rules.d/.

The files in this directory start with a two-digit number, followed by a descriptive name, and end with .rules. Functions inside these files are executed in the order they have been sorted in. For example, 00-foo.rules is sorted (and hence executed) before 60-bar.rules or even 90-default-privs.rules.

Inside the file, the script checks for the specified action ID, which is defined in the .policy file. For example, if you want to allow the command gparted to be executed by any member of the admin group, check for the action ID org.opensuse.policykit.gparted:

/* Allow users in admin group to run GParted without authentication */
polkit.addRule(function(action, subject) {
    if (action.id == "org.opensuse.policykit.gparted" &&
        subject.isInGroup("admin")) {
        return polkit.Result.YES;
    }
});

Find the description of all classes and methods of the functions in the PolKit API at http://www.freedesktop.org/software/polkit/docs/latest/ref-api.html.

9.4.3 Modifying Configuration Files for Implicit Privileges

SUSE Linux Enterprise Server ships with two sets of default authorizations, located in /etc/polkit-default-privs.standard and /etc/polkit-default-privs.restrictive. For more information, refer to Section 9.2.3, “Default Privileges”.

Custom privileges are defined in /etc/polkit-default-privs.local. Privileges defined here will always take precedence over the ones defined in the other configuration files. To define your custom set of privileges, do the following:

  1. Open /etc/polkit-default-privs.local. To define a privilege, add a line for each policy with the following format:

    <privilege_identifier>     <any session>:<inactive session>:<active session>

    For example:

    org.freedesktop.policykit.modify-defaults     auth_admin_keep_always

    The following values are valid for the SESSION placeholders:

    yes

    grant privilege

    no

    block

    auth_self

    user needs to authenticate with own password every time the privilege is requested

    auth_self_keep_session

    user needs to authenticate with own password once per session, privilege is granted for the whole session

    auth_self_keep_always

    user needs to authenticate with own password once, privilege is granted for the current and for future sessions

    auth_admin

    user needs to authenticate with root password every time the privilege is requested

    auth_admin_keep_session

    user needs to authenticate with root password once per session, privilege is granted for the whole session

    auth_admin_keep_always

    user needs to authenticate with root password once, privilege is granted for the current and for future sessions

  2. Run as root for changes to take effect:

    # /sbin/set_polkit_default_privs
  3. Optionally check the list of all privilege identifiers with the command pkaction.

9.5 Restoring the Default Privileges

SUSE Linux Enterprise Server comes with a predefined set of privileges that is activated by default and thus overrides the upstream defaults. For details, refer to Section 9.2.3, “Default Privileges”.

Since the graphical PolKit tools and the command line tools always operate on the upstream defaults, SUSE Linux Enterprise Server includes an additional command-line tool, set_polkit_default_privs. It resets privileges to the values defined in /etc/polkit-default-privs.*. However, the command set_polkit_default_privs will only reset policies that are set to the upstream defaults.

Procedure 9.1: Restoring the SUSE Linux Enterprise Server Defaults
  1. Make sure /etc/polkit-default-privs.local does not contain any overrides of the default policies.

    Important
    Important: Custom Policy Configuration

    Policies defined in /etc/polkit-default-privs.local will be applied on top of the defaults during the next step.

  2. To reset all policies to the upstream defaults first and then apply the SUSE Linux Enterprise Server defaults:

    rm -f /var/lib/polkit/* && set_polkit_default_privs

10 Access Control Lists in Linux

  • Filename: security_acls.xml
  • ID: cha.security.acls
Abstract

POSIX ACLs (access control lists) can be used as an expansion of the traditional permission concept for file system objects. With ACLs, permissions can be defined more flexibly than with the traditional permission concept.

The term POSIX ACL suggests that this is a true POSIX (portable operating system interface) standard. The respective draft standards POSIX 1003.1e and POSIX 1003.2c have been withdrawn for several reasons. Nevertheless, ACLs (as found on many systems belonging to the Unix family) are based on these drafts and the implementation of file system ACLs (as described in this chapter) follows these two standards.

10.1 Traditional File Permissions

Find detailed information about the traditional file permissions in the GNU Coreutils Info page, Node File permissions (info coreutils "File permissions"). More advanced features are the setuid, setgid, and sticky bit.

10.1.1 The setuid Bit

In certain situations, the access permissions may be too restrictive. Therefore, Linux has additional settings that enable the temporary change of the current user and group identity for a specific action. For example, the passwd program normally requires root permissions to access /etc/passwd. This file contains some important information, like the home directories of users and user and group IDs. Thus, a normal user would not be able to change passwd, because it would be too dangerous to grant all users direct access to this file. A possible solution to this problem is the setuid mechanism. setuid (set user ID) is a special file attribute that instructs the system to execute programs marked accordingly under a specific user ID. Consider the passwd command:

-rwsr-xr-x  1 root shadow 80036 2004-10-02 11:08 /usr/bin/passwd

You can see the s that denotes that the setuid bit is set for the user permission. By means of the setuid bit, all users starting the passwd command execute it as root.

10.1.2 The setgid Bit

The setuid bit applies to users. However, there is also an equivalent property for groups: the setgid bit. A program for which this bit was set runs under the group ID under which it was saved, no matter which user starts it. Therefore, in a directory with the setgid bit, all newly created files and subdirectories are assigned to the group to which the directory belongs. Consider the following example directory:

drwxrws--- 2 tux archive 48 Nov 19 17:12  backup

You can see the s that denotes that the setgid bit is set for the group permission. The owner of the directory and members of the group archive may access this directory. Users that are not members of this group are mapped to the respective group. The effective group ID of all written files will be archive. For example, a backup program that runs with the group ID archive can access this directory even without root privileges.

10.1.3 The Sticky Bit

There is also the sticky bit. It makes a difference whether it belongs to an executable program or a directory. If it belongs to a program, a file marked in this way is loaded to RAM to avoid needing to get it from the hard disk each time it is used. This attribute is used rarely, because modern hard disks are fast enough. If this bit is assigned to a directory, it prevents users from deleting each other's files. Typical examples include the /tmp and /var/tmp directories:

drwxrwxrwt 2 root root 1160 2002-11-19 17:15 /tmp

10.2 Advantages of ACLs

Traditionally, three permission sets are defined for each file object on a Linux system. These sets include the read (r), write (w), and execute (x) permissions for each of three types of users—the file owner, the group, and other users. In addition to that, it is possible to set the set user id, the set group id, and the sticky bit. This lean concept is fully adequate for most practical cases. However, for more complex scenarios or advanced applications, system administrators formerly needed to use several workarounds to circumvent the limitations of the traditional permission concept.

ACLs can be used as an extension of the traditional file permission concept. They allow the assignment of permissions to individual users or groups even if these do not correspond to the original owner or the owning group. Access control lists are a feature of the Linux kernel and are currently supported by ReiserFS, Ext2, Ext3, JFS, and XFS. Using ACLs, complex scenarios can be realized without implementing complex permission models on the application level.

The advantages of ACLs are evident if you want to replace a Windows server with a Linux server. Some connected workstations may continue to run under Windows even after the migration. The Linux system offers file and print services to the Windows clients with Samba. With Samba supporting access control lists, user permissions can be configured both on the Linux server and in Windows with a graphical user interface (only Windows NT and later). With winbindd, part of the Samba suite, it is even possible to assign permissions to users only existing in the Windows domain without any account on the Linux server.

10.3 Definitions

User Class

The conventional POSIX permission concept uses three classes of users for assigning permissions in the file system: the owner, the owning group, and other users. Three permission bits can be set for each user class, giving permission to read (r), write (w), and execute (x).

ACL

The user and group access permissions for all kinds of file system objects (files and directories) are determined by means of ACLs.

Default ACL

Default ACLs can only be applied to directories. They determine the permissions a file system object inherits from its parent directory when it is created.

ACL Entry

Each ACL consists of a set of ACL entries. An ACL entry contains a type, a qualifier for the user or group to which the entry refers, and a set of permissions. For some entry types, the qualifier for the group or users is undefined.

10.4 Handling ACLs

Table 10.1, “ACL Entry Types” summarizes the six possible types of ACL entries, each defining permissions for a user or a group of users. The owner entry defines the permissions of the user owning the file or directory. The owning group entry defines the permissions of the file's owning group. The superuser can change the owner or owning group with chown or chgrp, in which case the owner and owning group entries refer to the new owner and owning group. Each named user entry defines the permissions of the user specified in the entry's qualifier field. Each named group entry defines the permissions of the group specified in the entry's qualifier field. Only the named user and named group entries have a qualifier field that is not empty. The other entry defines the permissions of all other users.

The mask entry further limits the permissions granted by named user, named group, and owning group entries by defining which of the permissions in those entries are effective and which are masked. If permissions exist in one of the mentioned entries and in the mask, they are effective. Permissions contained only in the mask or only in the actual entry are not effective—meaning the permissions are not granted. All permissions defined in the owner and owning group entries are always effective. The example in Table 10.2, “Masking Access Permissions” demonstrates this mechanism.

There are two basic classes of ACLs: A minimum ACL contains only the entries for the types owner, owning group, and other, which correspond to the conventional permission bits for files and directories. An extended ACL goes beyond this. It must contain a mask entry and may contain several entries of the named user and named group types.

Table 10.1: ACL Entry Types

Type

Text Form

owner

user::rwx

named user

user:name:rwx

owning group

group::rwx

named group

group:name:rwx

mask

mask::rwx

other

other::rwx

Table 10.2: Masking Access Permissions

Entry Type

Text Form

Permissions

named user

user:geeko:r-x

r-x

mask

mask::rw-

rw-

effective permissions:

r--

10.4.1 ACL Entries and File Mode Permission Bits

Figure 10.1, “Minimum ACL: ACL Entries Compared to Permission Bits” and Figure 10.2, “Extended ACL: ACL Entries Compared to Permission Bits” illustrate the two cases of a minimum ACL and an extended ACL. The figures are structured in three blocks—the left block shows the type specifications of the ACL entries, the center block displays an example ACL, and the right block shows the respective permission bits according to the conventional permission concept (for example, as displayed by ls -l). In both cases, the owner class permissions are mapped to the ACL entry owner. Other class permissions are mapped to the respective ACL entry. However, the mapping of the group class permissions is different in the two cases.

Minimum ACL: ACL Entries Compared to Permission Bits
Figure 10.1: Minimum ACL: ACL Entries Compared to Permission Bits

In the case of a minimum ACL—without mask—the group class permissions are mapped to the ACL entry owning group. This is shown in Figure 10.1, “Minimum ACL: ACL Entries Compared to Permission Bits”. In the case of an extended ACL—with mask—the group class permissions are mapped to the mask entry. This is shown in Figure 10.2, “Extended ACL: ACL Entries Compared to Permission Bits”.

Extended ACL: ACL Entries Compared to Permission Bits
Figure 10.2: Extended ACL: ACL Entries Compared to Permission Bits

This mapping approach ensures the smooth interaction of applications, regardless of whether they have ACL support. The access permissions that were assigned by means of the permission bits represent the upper limit for all other fine adjustments made with an ACL. Changes made to the permission bits are reflected by the ACL and vice versa.

10.4.2 A Directory with an ACL

With getfacl and setfacl on the command line, you can access ACLs. The usage of these commands is demonstrated in the following example.

Before creating the directory, use the umask command to define which access permissions should be masked each time a file object is created. The command umask 027 sets the default permissions by giving the owner the full range of permissions (0), denying the group write access (2), and giving other users no permissions (7). umask actually masks the corresponding permission bits or turns them off. For details, consult the umask man page.

mkdir mydir creates the mydir directory with the default permissions as set by umask. Use ls -dl mydir to check whether all permissions were assigned correctly. The output for this example is:

drwxr-x--- ... tux project3 ... mydir

With getfacl mydir, check the initial state of the ACL. This gives information like:

# file: mydir
# owner: tux
# group: project3
user::rwx
group::r-x
other::---

The first three output lines display the name, owner, and owning group of the directory. The next three lines contain the three ACL entries owner, owning group, and other. In fact, in the case of this minimum ACL, the getfacl command does not produce any information you could not have obtained with ls.

Modify the ACL to assign read, write, and execute permissions to an additional user geeko and an additional group mascots with:

setfacl -m user:geeko:rwx,group:mascots:rwx mydir

The option -m prompts setfacl to modify the existing ACL. The following argument indicates the ACL entries to modify (multiple entries are separated by commas). The final part specifies the name of the directory to which these modifications should be applied. Use the getfacl command to take a look at the resulting ACL.

# file: mydir
# owner: tux
# group: project3
user::rwx
user:geeko:rwx
group::r-x
group:mascots:rwx
mask::rwx
other::---

In addition to the entries initiated for the user geeko and the group mascots, a mask entry has been generated. This mask entry is set automatically so that all permissions are effective. setfacl automatically adapts existing mask entries to the settings modified, unless you deactivate this feature with -n. The mask entry defines the maximum effective access permissions for all entries in the group class. This includes named user, named group, and owning group. The group class permission bits displayed by ls -dl mydir now correspond to the mask entry.

drwxrwx---+ ... tux project3 ... mydir

The first column of the output contains an additional + to indicate that there is an extended ACL for this item.

According to the output of the ls command, the permissions for the mask entry include write access. Traditionally, such permission bits would mean that the owning group (here project3) also has write access to the directory mydir.

However, the effective access permissions for the owning group correspond to the overlapping portion of the permissions defined for the owning group and for the mask—which is r-x in our example (see Table 10.2, “Masking Access Permissions”). As far as the effective permissions of the owning group in this example are concerned, nothing has changed even after the addition of the ACL entries.

Edit the mask entry with setfacl or chmod. For example, use chmod g-w mydir. ls -dl mydir then shows:

drwxr-x---+ ... tux project3 ... mydir

getfacl mydir provides the following output:

# file: mydir
# owner: tux
# group: project3
user::rwx
user:geeko:rwx          # effective: r-x
group::r-x
group:mascots:rwx       # effective: r-x
mask::r-x
other::---

After executing chmod to remove the write permission from the group class bits, the output of ls is sufficient to see that the mask bits must have changed accordingly: write permission is again limited to the owner of mydir. The output of the getfacl confirms this. This output includes a comment for all those entries in which the effective permission bits do not correspond to the original permissions, because they are filtered according to the mask entry. The original permissions can be restored at any time with chmod g+w mydir.

10.4.3 A Directory with a Default ACL

Directories can have a default ACL, which is a special kind of ACL defining the access permissions that objects in the directory inherit when they are created. A default ACL affects both subdirectories and files.

10.4.3.1 Effects of a Default ACL

There are two ways in which the permissions of a directory's default ACL are passed to the files and subdirectories:

  • A subdirectory inherits the default ACL of the parent directory both as its default ACL and as an ACL.

  • A file inherits the default ACL as its ACL.

All system calls that create file system objects use a mode parameter that defines the access permissions for the newly created file system object. If the parent directory does not have a default ACL, the permission bits as defined by the umask are subtracted from the permissions as passed by the mode parameter, with the result being assigned to the new object. If a default ACL exists for the parent directory, the permission bits assigned to the new object correspond to the overlapping portion of the permissions of the mode parameter and those that are defined in the default ACL. The umask is disregarded in this case.

10.4.3.2 Application of Default ACLs

The following three examples show the main operations for directories and default ACLs:

  1. Add a default ACL to the existing directory mydir with:

    setfacl -d -m group:mascots:r-x mydir

    The option -d of the setfacl command prompts setfacl to perform the following modifications (option -m) in the default ACL.

    Take a closer look at the result of this command:

    getfacl mydir
    
    # file: mydir
    # owner: tux
    # group: project3
    user::rwx
    user:geeko:rwx
    group::r-x
    group:mascots:rwx
    mask::rwx
    other::---
    default:user::rwx
    default:group::r-x
    default:group:mascots:r-x
    default:mask::r-x
    default:other::---

    getfacl returns both the ACL and the default ACL. The default ACL is formed by all lines that start with default. Although you merely executed the setfacl command with an entry for the mascots group for the default ACL, setfacl automatically copied all other entries from the ACL to create a valid default ACL. Default ACLs do not have an immediate effect on access permissions. They only come into play when file system objects are created. These new objects inherit permissions only from the default ACL of their parent directory.

  2. In the next example, use mkdir to create a subdirectory in mydir, which inherits the default ACL.

    mkdir mydir/mysubdir
    
    getfacl mydir/mysubdir
    
    # file: mydir/mysubdir
    # owner: tux
    # group: project3
    user::rwx
    group::r-x
    group:mascots:r-x
    mask::r-x
    other::---
    default:user::rwx
    default:group::r-x
    default:group:mascots:r-x
    default:mask::r-x
    default:other::---

    As expected, the newly-created subdirectory mysubdir has the permissions from the default ACL of the parent directory. The ACL of mysubdir is an exact reflection of the default ACL of mydir. The default ACL that this directory will hand down to its subordinate objects is also the same.

  3. Use touch to create a file in the mydir directory, for example, touch mydir/myfile. ls -l mydir/myfile then shows:

    -rw-r-----+ ... tux project3 ... mydir/myfile

    The output of getfacl mydir/myfile is:

    # file: mydir/myfile
    # owner: tux
    # group: project3
    user::rw-
    group::r-x          # effective:r--
    group:mascots:r-x   # effective:r--
    mask::r--
    other::---

    touch uses a mode with the value 0666 when creating new files, which means that the files are created with read and write permissions for all user classes, provided no other restrictions exist in umask or in the default ACL (see Section 10.4.3.1, “Effects of a Default ACL”). In effect, this means that all access permissions not contained in the mode value are removed from the respective ACL entries. Although no permissions were removed from the ACL entry of the group class, the mask entry was modified to mask permissions not set in mode.

    This approach ensures the smooth interaction of applications (such as compilers) with ACLs. You can create files with restricted access permissions and subsequently mark them as executable. The mask mechanism guarantees that the right users and groups can execute them as desired.

10.4.4 The ACL Check Algorithm

A check algorithm is applied before any process or application is granted access to an ACL-protected file system object. As a basic rule, the ACL entries are examined in the following sequence: owner, named user, owning group or named group, and other. The access is handled in accordance with the entry that best suits the process. Permissions do not accumulate.

Things are more complicated if a process belongs to more than one group and would potentially suit several group entries. An entry is randomly selected from the suitable entries with the required permissions. It is irrelevant which of the entries triggers the final result access granted. Likewise, if none of the suitable group entries contain the required permissions, a randomly selected entry triggers the final result access denied.

10.5 ACL Support in Applications

ACLs can be used to implement very complex permission scenarios that meet the requirements of modern applications. The traditional permission concept and ACLs can be combined in a smart manner. The basic file commands (cp, mv, ls, etc.) support ACLs, as do Samba and Nautilus.

Unfortunately, many editors and file managers still lack ACL support. When copying files with Emacs, for example, the ACLs of these files are lost. When modifying files with an editor, the ACLs of files are sometimes preserved and sometimes not, depending on the backup mode of the editor used. If the editor writes the changes to the original file, the ACL is preserved. If the editor saves the updated contents to a new file that is subsequently renamed to the old file name, the ACLs may be lost, unless the editor supports ACLs. Except for the star archiver, there are currently no backup applications that preserve ACLs.

10.6 For More Information

For more information about ACLs, see the man pages for getfacl(1), acl(5), and setfacl(1).

11 Encrypting Partitions and Files

  • Filename: security_cryptofs.xml
  • ID: cha.security.cryptofs

Encrypting files, partitions, and entire disks prevents unauthorized access to your data and protects your confidential files and documents.

You can choose between the following encryption options:

Encrypting a Hard Disk Partition

It is possible to create an encrypted partition with YaST during installation or in an already installed system. For further info, see Section 11.1.1, “Creating an Encrypted Partition during Installation” and Section 11.1.2, “Creating an Encrypted Partition on a Running System”. This option can also be used for removable media, such as external hard disks, as described in Section 11.1.4, “Encrypting the Content of Removable Media”.

Creating an Encrypted Virtual Disk

You can create a file-based encrypted virtual disk on your hard disk or a removable medium with YaST. The encrypted virtual disk can then be used as a regular folder for storing files or directories. For more information, refer to Section 11.1.3, “Creating an Encrypted Virtual Disk”.

Encrypting Home Directories

With SUSE Linux Enterprise Server, you can also create encrypted user home directories. When the user logs in to the system, the encrypted home directory is mounted and the contents are made available to the user. Refer to Section 11.2, “Using Encrypted Home Directories” for more information.

Encrypting Single Files with GPG

To quickly encrypt one or several files, you can use the GPG tool. See Section 11.3, “Encrypting Files with GPG” for more information.

Warning
Warning: Encryption Offers Limited Protection

Encryption methods described in this chapter cannot protect your running system from being compromised. After the encrypted volume is successfully mounted, everybody with appropriate permissions can access it. However, encrypted media are useful in case of loss or theft of your computer, or to prevent unauthorized individuals from reading your confidential data.

11.1 Setting Up an Encrypted File System with YaST

Use YaST to encrypt partitions or parts of your file system during installation or in an already installed system. However, encrypting a partition in an already-installed system is more difficult, because you need to resize and change existing partitions. In such cases, it may be more convenient to create an encrypted file of a defined size, in which to store other files or parts of your file system. To encrypt an entire partition, dedicate a partition for encryption in the partition layout. The standard partitioning proposal as suggested by YaST, does not include an encrypted partition by default. Add it manually in the partitioning dialog.

11.1.1 Creating an Encrypted Partition during Installation

Warning
Warning: Password Input

Make sure to memorize the password for your encrypted partitions well. Without that password, you cannot access or restore the encrypted data.

The YaST expert dialog for partitioning offers the options needed for creating an encrypted partition. To create a new encrypted partition proceed as follows:

  1. Run the YaST Expert Partitioner with System › Partitioner.

  2. Select a hard disk, click Add, and select a primary or an extended partition.

  3. Select the partition size or the region to use on the disk.

  4. Select the file system, and mount point of this partition.

  5. Activate the Encrypt device check box.

    Note
    Note: Additional Software Required

    After checking Encrypt device, a pop-up window asking for installing additional software may appear. Confirm to install all the required packages to ensure that the encrypted partition works well.

  6. If the encrypted file system needs to be mounted only when necessary, enable Do not mount partition in the Fstab Options. otherwise enable Mount partition and enter the mount point.

  7. Click Next and enter a password which is used to encrypt this partition. This password is not displayed. To prevent typing errors, you need to enter the password twice.

  8. Complete the process by clicking Finish. The newly-encrypted partition is now created.

During the boot process, the operating system asks for the password before mounting any encrypted partition which is set to be auto-mounted in /etc/fstab. Such a partition is then available to all users when it has been mounted.

To skip mounting the encrypted partition during start-up, press Enter when prompted for the password. Then decline the offer to enter the password again. In this case, the encrypted file system is not mounted and the operating system continues booting, blocking access to your data.

To mount an encrypted partition which is not mounted during the boot process, open a file manager and click the partition entry in the pane listing common places on your file system. You will be prompted for a password and the partition will be mounted.

When you are installing your system on a machine where partitions already exist, you can also decide to encrypt an existing partition during installation. In this case follow the description in Section 11.1.2, “Creating an Encrypted Partition on a Running System” and be aware that this action destroys all data on the existing partition.

11.1.2 Creating an Encrypted Partition on a Running System

Warning
Warning: Activating Encryption on a Running System

It is also possible to create encrypted partitions on a running system. However, encrypting an existing partition destroys all data on it, and requires re-sizing and restructuring of existing partitions.

On a running system, select System › Partitioner in the YaST control center. Click Yes to proceed. In the Expert Partitioner, select the partition to encrypt and click Edit. The rest of the procedure is the same as described in Section 11.1.1, “Creating an Encrypted Partition during Installation”.

11.1.3 Creating an Encrypted Virtual Disk

Instead of encrypting an entire disk or partition, you can use YaST to set up a file-based encrypted virtual disk. It will appear as a regular file in the file system, but can be mounted and used like a regular folder. Unlike encrypted partitions, encrypted virtual disks can be created without re-partitioning the hard disk.

To set up an encrypted virtual disk, you need to create an empty file first (this file is called loop file). In the terminal, switch to the desired directory and run the touch FILE command (where FILE is the desired name, for example: secret). It is also recommended to create an empty directory that will act as a mount point for the encrypted virtual disk. To do this, use the mkdir DIR command (replace DIR with the actual path and directory name, for example: ~/my_docs).

To set up an encrypted virtual disk, launch YaST, switch to the System section, and start Partitioner. Switch to the Crypt Files section and press Add Crypt File. Enter the path to the created loop file into the Path Name of Loop File field. Enable the Create Loop File option, specify the desired size, and press Next. In the Mount Point field, enter the path to the directory that serves as a mount point (in this example, it is ~/my_docs). Make sure that the Encrypt Device option is enabled and press Next. Provide the desired password and press Finish.

11.1.4 Encrypting the Content of Removable Media

YaST treats removable media (like external hard disks or flash disks) the same as any other storage device. Virtual disks or partitions on external media can be encrypted as described above. However, you should disable mounting at boot time, because removable media is usually connected only when the system is up and running.

If you encrypted your removable device with YaST, the GNOME desktop automatically recognizes the encrypted partition and prompts for the password when the device is detected. If you plug in a FAT-formatted removable device when running GNOME, the desktop user entering the password automatically becomes the owner of the device. For devices with a file system other than FAT, change the ownership explicitly for users other than root to give them read-write access to the device.

If you have created a virtual disk as described in Section 11.1.3, “Creating an Encrypted Virtual Disk” but with the loop file on a removable disk, then you need to mount the file manually as follows:

sudo cryptsetup luksOpen  FILE NAME
sudo mount /dev/mapper/NAME DIR

In the commands above, the FILE refers to the path to the loop file, NAME is a user-defined name, and DIR is the path to the mount point. For example:

sudo cryptsetup luksOpen /run/media/tux/usbstick/secret my_secret
sudo mount /dev/mapper/my_secret /home/tux/my_docs

11.2 Using Encrypted Home Directories

To protect data in home directories from unauthorized access, use the YaST user management module to encrypt home directories. You can create encrypted home directories for new or existing users. To encrypt or decrypt home directories of already existing users, you need to know their login password. See Section 16.3.3, “Managing Encrypted Home Directories” for instructions.

Encrypted home partitions are created within a virtual disk as described in Section 11.1.3, “Creating an Encrypted Virtual Disk”. Two files are created under /home for each encrypted home directory:

LOGIN.img

The image holding the directory

LOGIN.key

The image key, protected with the user's login password.

On login, the home directory automatically gets decrypted. Internally, it works through the PAM module called pam_mount. If you need to add an additional login method that provides encrypted home directories, you need to add this module to the respective configuration file in /etc/pam.d/. For more information, see Chapter 2, Authentication with PAM and the man page of pam_mount.

Warning
Warning: Security Restrictions

Encrypting a user's home directory does not provide strong security from other users. If strong security is required, the system should not be shared physically.

To enhance security, also encrypt the swap partition and the /tmp and /var/tmp directories, because these may contain temporary images of critical data. You can encrypt swap, /tmp, and /var/tmp with the YaST partitioner as described in Section 11.1.1, “Creating an Encrypted Partition during Installation” or Section 11.1.3, “Creating an Encrypted Virtual Disk”.

11.3 Encrypting Files with GPG

The GPG encryption software can be used to encrypt individual files and documents.

To encrypt a file with GPG, you need to generate a key pair first. To do this, run the gpg --gen-key and follow the on-screen instructions. When generating the key pair, GPG creates a user ID (UID) to identify the key based on your real name, comments, and email address. You need this UID (or just a part of it like your first name or email address) to specify the key you want to use to encrypt a file. To find the UID of an existing key, use the gpg --list-keys command. To encrypt a file use the following command:

gpg -e -r UID
  FILE

Replace UID with part of the UID (for example, your first name) and FILE with the file you want to encrypt. For example:

gpg -e -r Tux secret.txt

This command creates an encrypted version of the specified file recognizable by the .gpg file extension (in this example, it is secret.txt.gpg).

To decrypt an encrypted file, use the following command:

gpg -d -o DECRYPTED_FILE
  ENCRYPTED_FILE

Replace DECRYPTED_FILE with the desired name for the decrypted file and ENCRYPTED_FILE with the encrypted file you want to decrypt.

Keep that the encrypted file can be only decrypted using the same key that was used for encryption. If you want to share an encrypted file with another person, you have to use that person's public key to encrypt the file.

12 Certificate Store

  • Filename: security_certificatestore.xml
  • ID: cha.certstore
Abstract

Certificates play an important role in the authentication of companies and individuals. Usually certificates are administered by the application itself. In some cases, it makes sense to share certificates between applications. The certificate store is a common ground for Firefox, Evolution, and NetworkManager. This chapter explains some details.

The certificate store is a common database for Firefox, Evolution, and NetworkManager at the moment. Other applications that use certificates are not covered but may be in the future. If you have such an application, you can continue to use its private, separate configuration.

12.1 Activating Certificate Store

The configuration is mostly done in the background. To activate it, proceed as follows:

  1. Decide if you want to activate the certificate store globally (for every user on your system) or specifically to a certain user:

    • For every user.  Use the file /etc/profile.local

    • For a specific user.  Use the file ~/.bashrc

  2. Open the file from the previous step and insert the following line:

    export NSS_USE_SHARED_DB=1

    Save the file

  3. Log out of and log in to your desktop.

All the certificates are stored under $HOME/.local/var/pki/nssdb/.

12.2 Importing Certificates

To import a certificate into the certificate store, do the following:

  1. Start Firefox.

  2. Open the dialog from Edit › Preferences. Change to Advanced › Encryption and click View Certificates.

  3. Import your certificate depending on your type: use Servers to import server certificate, People to identify other, and Your Certificates to identify yourself.

13 Intrusion Detection with AIDE

  • Filename: security_aide.xml
  • ID: cha.aide
Abstract

Securing your systems is a mandatory task for any mission-critical system administrator. Because it is impossible to always guarantee that the system is not compromised, it is very important to do extra checks regularly (for example with cron) to ensure that the system is still under your control. This is where AIDE, the Advanced Intrusion Detection Environment, comes into play.

13.1 Why Use AIDE?

An easy check that often can reveal unwanted changes can be done by means of RPM. The package manager has a built-in verify function that checks all the managed files in the system for changes. To verify of all files, run the command rpm -Va. However, this command will also display changes in configuration files and you will need to do some filtering to detect important changes.

An additional problem to the method with RPM is that an intelligent attacker will modify rpm itself to hide any changes that might have been done by some kind of root-kit which allows the attacker to mask its intrusion and gain root privilege. To solve this, you should implement a secondary check that can also be run completely independent of the installed system.

13.2 Setting Up an AIDE Database

Important
Important: Initialize AIDE Database After Installation

Before you install your system, verify the checksum of your medium (see Section 40.2.1, “Checking Media”) to make sure you do not use a compromised source. After you have installed the system, initialize the AIDE database. To make sure that all went well during and after the installation, do an installation directly on the console, without any network attached to the computer. Do not leave the computer unattended or connected to any network before AIDE creates its database.

AIDE is not installed by default on SUSE Linux Enterprise Server. To install it, either use Computer › Install Software, or enter zypper install aide on the command line as root.

To tell AIDE which attributes of which files should be checked, use the /etc/aide.conf configuration file. It must be modified to become the actual configuration. The first section handles general parameters like the location of the AIDE database file. More relevant for local configurations are the Custom Rules and the Directories and Files sections. A typical rule looks like the following:

Binlib     = p+i+n+u+g+s+b+m+c+md5+sha1

After defining the variable Binlib, the respective check boxes are used in the files section. Important options include the following:

Table 13.1: Important AIDE Check Boxes

Option

Description

p

Check for the file permissions of the selected files or directories.

i

Check for the inode number. Every file name has a unique inode number that should not change.

n

Check for the number of links pointing to the relevant file.

u

Check if the owner of the file has changed.

g

Check if the group of the file has changed.

s

Check if the file size has changed.

b

Check if the block count used by the file has changed.

m

Check if the modification time of the file has changed.

c

Check if the files access time has changed.

md5

Check if the md5 checksum of the file has changed.

sha1

Check if the sha1 (160 Bit) checksum of the file has changed.

This is a configuration that checks for all files in /sbin with the options defined in Binlib but omits the /sbin/conf.d/ directory:

/sbin  Binlib
!/sbin/conf.d

To create the AIDE database, proceed as follows:

  1. Open /etc/aide.conf.

  2. Define which files should be checked with which check boxes. For a complete list of available check boxes, see /usr/share/doc/packages/aide/manual.html. The definition of the file selection needs some knowledge about regular expressions. Save your modifications.

  3. To check whether the configuration file is valid, run:

    aide --config-check

    Any output of this command is a hint that the configuration is not valid. For example, if you get the following output:

    aide --config-check
    35:syntax error:!
    35:Error while reading configuration:!
    Configuration error

    The error is to be expected in line 36 of /etc/aide.conf. Note that the error message contains the last successfully read line of the configuration file.

  4. Initialize the AIDE database. Run the command:

    aide -i
  5. Copy the generated database to a save location like a CD-R or DVD-R, a remote server or a flash disk for later use.

    Important
    Important:

    This step is essential as it avoids compromising your database. It is recommended to use a medium which can be written only once to prevent the database being modified. Never leave the database on the computer which you want to monitor.

13.3 Local AIDE Checks

To perform a file system check, proceed as follows:

  1. Rename the database:

    mv /var/lib/aide/aide.db.new /var/lib/aide/aide.db
  2. After any configuration change, you always need to re-initialize the AIDE database and subsequently move the newly generated database. It is also a good idea to make a backup of this database. See Section 13.2, “Setting Up an AIDE Database” for more information.

  3. Perform the check with the following command:

    aide --check

If the output is empty, everything is fine. If AIDE found changes, it displays a summary of changes, for example:

aide --check
AIDE found differences between database and filesystem!!

Summary:
  Total number of files:        1992
  Added files:                  0
  Removed files:                0
  Changed files:                1

To learn about the actual changes, increase the verbose level of the check with the parameter -V. For the previous example, this could look like the following:

aide --check -V
AIDE found differences between database and filesystem!!
Start timestamp: 2009-02-18 15:14:10

Summary:
  Total number of files:        1992
  Added files:                  0
  Removed files:                0
  Changed files:                1


---------------------------------------------------
Changed files:
---------------------------------------------------

changed: /etc/passwd

--------------------------------------------------
Detailed information about changes:
---------------------------------------------------


File: /etc/passwd
  Mtime    : 2009-02-18 15:11:02              , 2009-02-18 15:11:47
  Ctime    : 2009-02-18 15:11:02              , 2009-02-18 15:11:47

In this example, the file /etc/passwd was touched to demonstrate the effect.

13.4 System Independent Checking

To avoid risk, it is advisable to also run the AIDE binary from a trusted source. This excludes the risk that some attacker also modified the aide binary to hide its traces.

To accomplish this task, AIDE must be run from a rescue system that is independent of the installed system. With SUSE Linux Enterprise Server it is relatively easy to extend the rescue system with arbitrary programs, and thus add the needed functionality.

Before you can start using the rescue system, you need to provide two packages to the system. These are included with the same syntax as you would add a driver update disk to the system. For a detailed description about the possibilities of linuxrc that are used for this purpose, see http://en.opensuse.org/SDB:Linuxrc. In the following, one possible way to accomplish this task is discussed.

Procedure 13.1: Starting a Rescue System with AIDE
  1. Provide an FTP server as a second machine.

  2. Copy the packages aide and mhash to the FTP server directory, in our case /srv/ftp/. Replace the placeholders ARCH and VERSION with the corresponding values:

    cp DVD1/suse/ARCH/aideVERSION.ARCH.rpm /srv/ftp
    cp DVD1/suse/ARCH/mhashVERSION.ARCH.rpm /srv/ftp
  3. Create an info file /srv/ftp/info.txt that provides the needed boot parameters for the rescue system:

    dud:ftp://ftp.example.com/aideVERSION.ARCH.rpm
    dud:ftp://ftp.example.com/mhashVERSION.ARCH.rpm

    Replace your FTP domain name, VERSION and ARCH with the values used on your system.

  4. Restart the server that needs to go through an AIDE check with the Rescue system from your DVD. Add the following string to the boot parameters:

    info=ftp://ftp.example.com/info.txt

    This parameter tells linuxrc to also read in all information from the info.txt file.

After the rescue system has booted, the AIDE program is ready for use.

13.5 For More Information

Information about AIDE is available at the following places:

Part III Network Security

14 SSH: Secure Network Operations

In networked environments, it is often necessary to access hosts from a remote location. If a user sends login and password strings for authentication purposes as plain text, they could be intercepted and misused to gain access to that user account. This would open all the user's files to an attacker and the illegal account could be used to obtain administrator or root access, or to penetrate other systems. In the past, remote connections were established with telnet, rsh or rlogin, which offered no guards against eavesdropping in the form of encryption or other security mechanisms. There are other unprotected communication channels, like the traditional FTP protocol and some remote copying programs like rcp.

15 Masquerading and Firewalls

Whenever Linux is used in a network environment, you can use the kernel functions that allow the manipulation of network packets to maintain a separation between internal and external network areas. The Linux netfilter framework provides the means to establish an effective firewall that keeps differ…

16 Configuring a VPN Server

Today, Internet connections are cheap and available almost everywhere. However, not all connections are secure. Using a Virtual Private Network (VPN), you can create a secure network within an insecure network such as the Internet or Wi-Fi. It can be implemented in different ways and serves several purposes. In this chapter, we focus on the OpenVPN implementation to link branch offices via secure wide area networks (WANs).

17 Managing X.509 Certification

An increasing number of authentication mechanisms are based on cryptographic procedures. Digital certificates that assign cryptographic keys to their owners play an important role in this context. These certificates are used for communication and can also be found, for example, on company ID cards. The generation and administration of certificates is mostly handled by official institutions that offer this as a commercial service. In some cases, however, it may make sense to carry out these tasks yourself. For example, if a company does not want to pass personal data to third parties.

YaST provides two modules for certification, which offer basic management functions for digital X.509 certificates. The following sections explain the basics of digital certification and how to use YaST to create and administer certificates of this type.

14 SSH: Secure Network Operations

  • Filename: security_ssh.xml
  • ID: cha.ssh
Abstract

In networked environments, it is often necessary to access hosts from a remote location. If a user sends login and password strings for authentication purposes as plain text, they could be intercepted and misused to gain access to that user account. This would open all the user's files to an attacker and the illegal account could be used to obtain administrator or root access, or to penetrate other systems. In the past, remote connections were established with telnet, rsh or rlogin, which offered no guards against eavesdropping in the form of encryption or other security mechanisms. There are other unprotected communication channels, like the traditional FTP protocol and some remote copying programs like rcp.

The SSH suite provides the necessary protection by encrypting the authentication strings (usually a login name and a password) and all the other data exchanged between the hosts. With SSH, the data flow could still be recorded by a third party, but the contents are encrypted and cannot be reverted to plain text unless the encryption key is known. So SSH enables secure communication over insecure networks, such as the Internet. The SSH implementation coming with SUSE Linux Enterprise Server is OpenSSH.

SUSE Linux Enterprise Server installs the OpenSSH package by default providing the commands ssh, scp, and sftp. In the default configuration, remote access of a SUSE Linux Enterprise Server system is only possible with the OpenSSH utilities, and only if the sshd is running and the firewall permits access.

SSH on SUSE Linux Enterprise Server uses cryptographic hardware acceleration if available. As a result, the transfer of large quantities of data through an SSH connection is considerably faster than without cryptographic hardware. As an additional benefit, the CPU will see a significant reduction in load.

14.1 ssh—Secure Shell

With ssh it is possible to log in to remote systems and to work interactively. To log in to the host sun as user tux enter one of the following commands:

ssh tux@sun
ssh -l tux sun

If the user name is the same on both machines, you can omit it. Using ssh sun is sufficient. The remote host prompts for the remote user's password. After a successful authentication, you can work on the remote command line or use interactive applications, such as YaST in text mode.

Furthermore, ssh offers the possibility to run non-interactive commands on remote systems using ssh HOST COMMAND. COMMAND needs to be properly quoted. Multiple commands can be concatenated as on a local shell.

ssh root@sun "dmesg -T | tail -n 25"
ssh root@sun "cat /etc/issue && uptime"

14.1.1 Starting X Applications on a Remote Host

SSH also simplifies the use of remote X applications. If you run ssh with the -X option, the DISPLAY variable is automatically set on the remote machine and all X output is exported to the local machine over the existing SSH connection. At the same time, X applications started remotely cannot be intercepted by unauthorized individuals.

14.1.2 Agent Forwarding

By adding the -A option, the ssh-agent authentication mechanism is carried over to the next machine. This way, you can work from different machines without having to enter a password, but only if you have distributed your public key to the destination hosts and properly saved it there. Refer to Section 14.5.2, “Copying an SSH Key” for details.

This mechanism is deactivated in the default settings, but can be permanently activated at any time in the systemwide configuration file /etc/ssh/sshd_config by setting AllowAgentForwarding yes.

14.2 scp—Secure Copy

scp copies files to or from a remote machine. If the user name on jupiter is different than the user name on sun, specify the latter using the USER_NAME@host format. If the file should be copied into a directory other than the remote user's home directory, specify it as sun:DIRECTORY. The following examples show how to copy a file from a local to a remote machine and vice versa.

# local -> remote
scp ~/MyLetter.tex tux@sun:/tmp
# remote -> local
scp tux@sun:/tmp/MyLetter.tex ~
Tip
Tip: The -l Option

With the ssh command, the option -l can be used to specify a remote user (as an alternative to the USER_NAME@host format). With scp the option -l is used to limit the bandwidth consumed by scp.

After the correct password is entered, scp starts the data transfer. It displays a progress bar and the time remaining for each file that is copied. Suppress all output with the -q option.

scp also provides a recursive copying feature for entire directories. The command

scp -r src/ sun:backup/

copies the entire contents of the directory src including all subdirectories to the ~/backup directory on the host sun. If this subdirectory does not exist, it is created automatically.

The -p option tells scp to leave the time stamp of files unchanged. -C compresses the data transfer. This minimizes the data volume to transfer, but creates a heavier burden on the processors of both machines.

14.3 sftp—Secure File Transfer

14.3.1 Using sftp

If you want to copy several files from or to different locations, sftp is a convenient alternative to scp. It opens a shell with a set of commands similar to a regular FTP shell. Type help at the sftp-prompt to get a list of available commands. More details are available from the sftp man page.

sftp sun
Enter passphrase for key '/home/tux/.ssh/id_rsa':
Connected to sun.
sftp> help
Available commands:
bye                                Quit sftp
cd path                            Change remote directory to 'path'
[...]

14.3.2 Setting Permissions for File Uploads

As with a regular FTP server, a user cannot only download, but also upload files to a remote machine running an SFTP server by using the put command. By default the files will be uploaded to the remote host with the same permissions as on the local host. There are two options to automatically alter these permissions:

Setting a umask

A umask works as a filter against the permissions of the original file on the local host. It can only withdraw permissions:

Table 14.1:

permissions original

umask

permissions uploaded

0666

0002

0664

0600

0002

0600

0775

0025

0750

To apply a umask on an SFTP server, edit the file /etc/ssh/sshd_configuration. Search for the line beginning with Subsystem sftp and add the -u parameter with the desired setting, for example:

Subsystem sftp /usr/lib/ssh/sftp-server -u 0002
Explicitly Setting the Permissions

Explicitly setting the permissions sets the same permissions for all files uploaded via SFTP. Specify a three-digit pattern such as 600, 644, or 755 with -u. When both -m and -u are specified, -u is ignored.

To apply explicit permissions for uploaded files on an SFTP server, edit the file /etc/ssh/sshd_configuration. Search for the line beginning with Subsystem sftp and add the -m parameter with the desired setting, for example:

Subsystem sftp /usr/lib/ssh/sftp-server -m 600

14.4 The SSH Daemon (sshd)

To work with the SSH client programs ssh and scp, a server (the SSH daemon) must be running in the background, listening for connections on TCP/IP port 22. The daemon generates three key pairs when starting for the first time. Each key pair consists of a private and a public key. Therefore, this procedure is called public key-based. To guarantee the security of the communication via SSH, access to the private key files must be restricted to the system administrator. The file permissions are set accordingly by the default installation. The private keys are only required locally by the SSH daemon and must not be given to anyone else. The public key components (recognizable by the name extension .pub) are sent to the client requesting the connection. They are readable for all users.

A connection is initiated by the SSH client. The waiting SSH daemon and the requesting SSH client exchange identification data to compare the protocol and software versions, and to prevent connections through the wrong port. Because a child process of the original SSH daemon replies to the request, several SSH connections can be made simultaneously.

For the communication between SSH server and SSH client, OpenSSH supports versions 1 and 2 of the SSH protocol. Version 2 of the SSH protocol is used by default. Override this to use version 1 of protocol with the -1 option.

When using version 1 of SSH, the server sends its public host key and a server key, which is regenerated by the SSH daemon every hour. Both allow the SSH client to encrypt a freely chosen session key, which is sent to the SSH server. The SSH client also tells the server which encryption method (cipher) to use. Version 2 of the SSH protocol does not require a server key. Both sides use an algorithm according to Diffie-Hellman to exchange their keys.

The private host and server keys are absolutely required to decrypt the session key and cannot be derived from the public parts. Only the contacted SSH daemon can decrypt the session key using its private keys. This initial connection phase can be watched closely by turning on verbose debugging using the -v option of the SSH client.

Tip
Tip: Viewing the SSH Daemon Log File

To watch the log entries from the sshd use the following command:

tux > sudo journalctl -u sshd

14.4.1 Maintaining SSH Keys

It is recommended to back up the private and public keys stored in /etc/ssh/ in a secure, external location. In this way, key modifications can be detected or the old ones can be used again after having installed a new system.

Tip
Tip: Existing SSH Host Keys

If you install SUSE Linux Enterprise Server on a machine with existing Linux installations, the installation routine automatically imports the SSH host key with the most recent access time from an existing installation.

When establishing a secure connection with a remote host for the first time, the client stores all public host keys in ~/.ssh/known_hosts. This prevents any man-in-the-middle attacks—attempts by foreign SSH servers to use spoofed names and IP addresses. Such attacks are detected either by a host key that is not included in ~/.ssh/known_hosts, or by the server's inability to decrypt the session key in the absence of an appropriate private counterpart.

If the public keys of a host have changed (that needs to be verified before connecting to such a server), the offending keys can be removed with ssh-keygen -r HOSTNAME.

14.4.2 Rotating Host Keys

As of version 6.8, OpenSSH comes with a protocol extension that supports host key rotation. It makes sense to replace keys, if you are still using weak keys such as 1024-bit RSA keys. It is strongly recommended to replace such a key and go for 2048-bit DSA keys or something even better. The client will then use the best host key.

Tip
Tip: Restarting sshd

After installing new host keys on the server, restart sshd.

This protocol extension can inform a client of all the new host keys on the server, if the user initiates a connection with ssh. Then, the software on the client updates ~/.ssh/known_hosts, and the user is not required to accept new keys of previously known and trusted hosts manually. The local known_hosts file will contain all the host keys of the remote hosts, in addition to the one that authenticated the host during this session.

Once the administrator of the server knows that all the clients have fetched the new keys, they can remove the old keys. The protocol extension ensures that the obsolete keys will be removed from the client's configuration, too. The key removal occurs while initiating an ssh session.

For more information, see:

14.5 SSH Authentication Mechanisms

In its simplest form, authentication is done by entering the user's password just as if logging in locally. However, having to memorize passwords of several users on remote machines is inefficient. What is more, these passwords may change. On the other hand—when granting root access—an administrator needs to be able to quickly revoke such a permission without having to change the root password.

To accomplish a login that does not require to enter the remote user's password, SSH uses another key pair, which needs to be generated by the user. It consists of a public (id_rsa.pub or id_dsa.pub) and a private key (id_rsa or id_dsa).

To be able to log in without having to specify the remote user's password, the public key of the SSH user must be in ~/.ssh/authorized_keys. This approach also ensures that the remote user has got full control: adding the key requires the remote user's password and removing the key revokes the permission to log in from remote.

For maximum security such a key should be protected by a passphrase which needs to be entered every time you use ssh, scp, or sftp. Contrary to the simple authentication, this passphrase is independent from the remote user and therefore always the same.

An alternative to the key-based authentication described above, SSH also offers a host-based authentication. With host-based authentication, users on a trusted host can log in to another host on which this feature is enabled using the same user name. SUSE Linux Enterprise Server is set up for using key-based authentication, covering setting up host-based authentication on SUSE Linux Enterprise Server is beyond the scope of this manual.

Note
Note: File Permissions for Host-Based Authentication

If the host-based authentication is to be used, the file /usr/lib/ssh/ssh-keysign (32-bit systems) or /usr/lib64/ssh/ssh-keysign (64-bit systems) should have the setuid bit set, which is not the default setting in SUSE Linux Enterprise Server. In such case, set the file permissions manually. You should use /etc/permissions.local for this purpose, to make sure that the setuid bit is preserved after security updates of openssh.

14.5.1 Generating an SSH Key

  1. To generate a key with default parameters (RSA, 2048 bits), enter the command ssh-keygen.

  2. Accept the default location to store the key (~/.ssh/id_rsa) by pressing Enter (strongly recommended) or enter an alternative location.

  3. Enter a passphrase consisting of 10 to 30 characters. The same rules as for creating safe passwords apply. It is strongly advised to refrain from specifying no passphrase.

You should make absolutely sure that the private key is not accessible by anyone other than yourself (always set its permissions to 0600). The private key must never fall into the hands of another person.

To change the password of an existing key pair, use the command ssh-keygen -p.

14.5.2 Copying an SSH Key

To copy a public SSH key to ~/.ssh/authorized_keys of a user on a remote machine, use the command ssh-copy-id. To copy your personal key stored under ~/.ssh/id_rsa.pub you may use the short form. To copy DSA keys or keys of other users, you need to specify the path:

# ~/.ssh/id_rsa.pub
ssh-copy-id -i tux@sun

# ~/.ssh/id_dsa.pub
ssh-copy-id -i ~/.ssh/id_dsa.pub  tux@sun

# ~notme/.ssh/id_rsa.pub
ssh-copy-id -i ~notme/.ssh/id_rsa.pub  tux@sun

To successfully copy the key, you need to enter the remote user's password. To remove an existing key, manually edit ~/.ssh/authorized_keys.

14.5.3 Using the ssh-agent

When doing lots of secure shell operations it is cumbersome to type the SSH passphrase for each such operation. Therefore, the SSH package provides another tool, ssh-agent, which retains the private keys for the duration of an X or terminal session. All other windows or programs are started as clients to the ssh-agent. By starting the agent, a set of environment variables is set, which will be used by ssh, scp, or sftp to locate the agent for automatic login. See the ssh-agent man page for details.

After the ssh-agent is started, you need to add your keys by using ssh-add. It will prompt for the passphrase. After the password has been provided once, you can use the secure shell commands within the running session without having to authenticate again.

14.5.3.1 Using ssh-agent in an X Session

On SUSE Linux Enterprise Server, the ssh-agent is automatically started by the GNOME display manager. To also invoke ssh-add to add your keys to the agent at the beginning of an X session, do the following:

  1. Log in as the desired user and check whether the file ~/.xinitrc exists.

  2. If it does not exist, use an existing template or copy it from /etc/skel:

    if [ -f ~/.xinitrc.template ]; then mv ~/.xinitrc.template ~/.xinitrc; \
    else cp /etc/skel/.xinitrc.template ~/.xinitrc; fi
  3. If you have copied the template, search for the following lines and uncomment them. If ~/.xinitrc already existed, add the following lines (without comment signs).

    # if test -S "$SSH_AUTH_SOCK" -a -x "$SSH_ASKPASS"; then
    #       ssh-add < /dev/null
    # fi
  4. When starting a new X session, you will be prompted for your SSH passphrase.

14.5.3.2 Using ssh-agent in a Terminal Session

In a terminal session you need to manually start the ssh-agent and then call ssh-add afterward. There are two ways to start the agent. The first example given below starts a new Bash shell on top of your existing shell. The second example starts the agent in the existing shell and modifies the environment as needed.

ssh-agent -s /bin/bash
eval $(ssh-agent)

After the agent has been started, run ssh-add to provide the agent with your keys.

14.6 Port Forwarding

ssh can also be used to redirect TCP/IP connections. This feature, also called SSH tunneling, redirects TCP connections to a certain port to another machine via an encrypted channel.

With the following command, any connection directed to jupiter port 25 (SMTP) is redirected to the SMTP port on sun. This is especially useful for those using SMTP servers without SMTP-AUTH or POP-before-SMTP features. From any arbitrary location connected to a network, e-mail can be transferred to the home mail server for delivery.

ssh -L 25:sun:25 jupiter

Similarly, all POP3 requests (port 110) on jupiter can be forwarded to the POP3 port of sun with this command:

ssh -L 110:sun:110 jupiter

Both commands must be executed as root, because the connection is made to privileged local ports. E-mail is sent and retrieved by normal users in an existing SSH connection. The SMTP and POP3 host must be set to localhost for this to work. Additional information can be found in the manual pages for each of the programs described above and in the OpenSSH package documentation under /usr/share/doc/packages/openssh.

14.7 For More Information

http://www.openssh.com

The home page of OpenSSH

http://en.wikibooks.org/wiki/OpenSSH

The OpenSSH Wikibook

man sshd

The man page of the OpenSSH daemon

man ssh_config

The man page of the OpenSSH SSH client configuration files

man scp , man sftp , man slogin , man ssh , man ssh-add , man ssh-agent , man ssh-copy-id , man ssh-keyconvert , man ssh-keygen , man ssh-keyscan

Man pages of several binary files to securely copy files (scp, sftp), to log in (slogin, ssh), and to manage keys.

/usr/share/doc/packages/openssh/README.SUSE , /usr/share/doc/packages/openssh/README.FIPS

SUSE package specific documentation; changes in defaults with respect to upstream, notes on FIPS mode etc.

15 Masquerading and Firewalls

  • Filename: security_firewall.xml
  • ID: cha.security.firewall

Whenever Linux is used in a network environment, you can use the kernel functions that allow the manipulation of network packets to maintain a separation between internal and external network areas. The Linux netfilter framework provides the means to establish an effective firewall that keeps different networks apart. Using iptables—a generic table structure for the definition of rule sets—precisely controls the packets allowed to pass a network interface. Such a packet filter can be set up using SuSEFirewall2 and the corresponding YaST module.

15.1 Packet Filtering with iptables

The components netfilter and iptables are responsible for the filtering and manipulation of network packets and for network address translation (NAT). The filtering criteria and any actions associated with them are stored in chains, which must be matched one after another by individual network packets as they arrive. The chains to match are stored in tables. The iptables command allows you to alter these tables and rule sets.

The Linux kernel maintains three tables, each for a particular category of functions of the packet filter:

filter

This table holds the bulk of the filter rules, because it implements the packet filtering mechanism in the stricter sense, which determines whether packets are let through (ACCEPT) or discarded (DROP), for example.

nat

This table defines any changes to the source and target addresses of packets. Using these functions also allows you to implement masquerading, which is a special case of NAT used to link a private network with the Internet.

mangle

The rules held in this table make it possible to manipulate values stored in IP headers (such as the type of service).

These tables contain several predefined chains to match packets:

PREROUTING

This chain is applied to incoming packets.

INPUT

This chain is applied to packets destined for the system's internal processes.

FORWARD

This chain is applied to packets that are only routed through the system.

OUTPUT

This chain is applied to packets originating from the system itself.

POSTROUTING

This chain is applied to all outgoing packets.

Figure 15.1, “iptables: A Packet's Possible Paths” illustrates the paths along which a network packet may travel on a given system. For the sake of simplicity, the figure lists tables as parts of chains, but in reality these chains are held within the tables themselves.

In the simplest case, an incoming packet destined for the system itself arrives at the eth0 interface. The packet is first referred to the PREROUTING chain of the mangle table then to the PREROUTING chain of the nat table. The following step, concerning the routing of the packet, determines that the actual target of the packet is a process of the system itself. After passing the INPUT chains of the mangle and the filter table, the packet finally reaches its target, provided that the rules of the filter table are actually matched.

iptables: A Packet's Possible Paths
Figure 15.1: iptables: A Packet's Possible Paths

15.2 Masquerading Basics

Masquerading is the Linux-specific form of NAT (network address translation) and can be used to connect a small LAN with the Internet. LAN hosts use IP addresses from the private range (see Section 16.1.2, “Netmasks and Routing”) and on the Internet official IP addresses are used. To be able to connect to the Internet, a LAN host's private address is translated to an official one. This is done on the router, which acts as the gateway between the LAN and the Internet. The underlying principle is a simple one: The router has more than one network interface, typically a network card and a separate interface connecting with the Internet. While the latter links the router with the outside world, one or several others link it with the LAN hosts. With these hosts in the local network connected to the network card (such as eth0) of the router, they can send any packets not destined for the local network to their default gateway or router.

Important
Important: Using the Correct Network Mask

When configuring your network, make sure both the broadcast address and the netmask are the same for all local hosts. Failing to do so prevents packets from being routed properly.

As mentioned, whenever one of the LAN hosts sends a packet destined for an Internet address, it goes to the default router. However, the router must be configured before it can forward such packets. For security reasons, this is not enabled in a default installation. To enable it, set the variable IP_FORWARD in the file /etc/sysconfig/sysctl to IP_FORWARD=yes.

The target host of the connection can see your router, but knows nothing about the host in your internal network where the packets originated. This is why the technique is called masquerading. Because of the address translation, the router is the first destination of any reply packets. The router must identify these incoming packets and translate their target addresses, so packets can be forwarded to the correct host in the local network.

With the routing of inbound traffic depending on the masquerading table, there is no way to open a connection to an internal host from the outside. For such a connection, there would be no entry in the table. In addition, any connection already established has a status entry assigned to it in the table, so the entry cannot be used by another connection.

As a consequence of all this, you might experience some problems with several application protocols, such as ICQ, cucme, IRC (DCC, CTCP), and FTP (in PORT mode). Web browsers, the standard FTP program, and many other programs use the PASV mode. This passive mode is much less problematic as far as packet filtering and masquerading are concerned.

15.3 Firewalling Basics

Firewall is probably the term most widely used to describe a mechanism that provides and manages a link between networks while also controlling the data flow between them. Strictly speaking, the mechanism described in this section is called a packet filter. A packet filter regulates the data flow according to certain criteria, such as protocols, ports, and IP addresses. This allows you to block packets that, according to their addresses, are not supposed to reach your network. To allow public access to your Web server, for example, explicitly open the corresponding port. However, a packet filter does not scan the contents of packets with legitimate addresses, such as those directed to your Web server. For example, if incoming packets were intended to compromise a CGI program on your Web server, the packet filter would still let them through.

A more effective but more complex mechanism is the combination of several types of systems, such as a packet filter interacting with an application gateway or proxy. In this case, the packet filter rejects any packets destined for disabled ports. Only packets directed to the application gateway are accepted. This gateway or proxy pretends to be the actual client of the server. In a sense, such a proxy could be considered a masquerading host on the protocol level used by the application. One example for such a proxy is Squid, an HTTP and FTP proxy server. To use Squid, the browser must be configured to communicate via the proxy. Any HTTP pages or FTP files requested are served from the proxy cache and objects not found in the cache are fetched from the Internet by the proxy.

The following section focuses on the packet filter that comes with SUSE Linux Enterprise Server. For further information about packet filtering and firewalling, read the Firewall HOWTO.

15.4 SuSEFirewall2

SuSEFirewall2 is a script that reads the variables set in /etc/sysconfig/SuSEfirewall2 to generate a set of iptables rules. It defines three security zones, although only the first and the second one are considered in the following sample configuration:

External Zone

Given that there is no way to control what is happening on the external network, the host needs to be protected from it. Usually, the external network is the Internet, but it could be another insecure network, such as a Wi-Fi.

Internal Zone

This refers to the private network, usually the LAN. If the hosts on this network use IP addresses from the private range (see Section 16.1.2, “Netmasks and Routing”), enable network address translation (NAT), so hosts on the internal network can access the external one. All ports are open in the internal zone. The main benefit of putting interfaces into the internal zone (rather than stopping the firewall) is that the firewall still runs, so when you add new interfaces, they will be put into the external zone by default. That way an interface is not accidentally open by default.

Demilitarized Zone (DMZ)

While hosts located in this zone can be reached both from the external and the internal network, they cannot access the internal network themselves. This setup can be used to put an additional line of defense in front of the internal network, because the DMZ systems are isolated from the internal network.

Note
Note: No Zone Assigned Behavior

By default, all network interfaces are set to no zone assigned. This mode behaves as the External Zone profile.

Any kind of network traffic not explicitly allowed by the filtering rule set is suppressed by iptables. Therefore, each of the interfaces with incoming traffic must be placed into one of the three zones. For each of the zones, define the services or protocols allowed. The rule set is only applied to packets originating from remote hosts. Locally generated packets are not captured by the firewall.

The configuration can be performed with YaST (see Section 15.4.1, “Configuring the Firewall with YaST”). It can also be made manually in the file /etc/sysconfig/SuSEfirewall2, which is well commented. Additionally, several example scenarios are available in /usr/share/doc/packages/SuSEfirewall2/EXAMPLES.

15.4.1 Configuring the Firewall with YaST

15.4.1.1 Opening Ports

In case your network interfaces are located in a firewall zone where network traffic is blocked on most ports, services that manage their network traffic via a blocked port, will not work. For example, SSH is a popular service that uses port 22. By default, this port is blocked on interfaces located in the external or demilitarized zone. To make SSH work, you need to open port 22 in the firewall configuration. This can be done with the YaST module Firewall.

Firewall Configuration: Allowed Services
Figure 15.2: Firewall Configuration: Allowed Services
Important
Important: Automatic Firewall Configuration

After the installation, YaST automatically starts a firewall on all configured interfaces. If a server is configured and activated on the system, YaST can modify the automatically generated firewall configuration with the options Open Ports on Selected Interface in Firewall or Open Ports on Firewall in the server configuration modules. Some server module dialogs include a Firewall Details button for activating additional services and ports. The YaST firewall configuration module can be used to activate, deactivate, or reconfigure the firewall.

Procedure 15.1: Manually Open Firewall Ports with YaST
  1. Open YaST › Security and Users › Firewall and switch to the Allowed Services tab.

  2. Select a zone at Allow Services for Selected Zone in which to open the port. It is not possible to open a port for several zones at once.

  3. Select a service from Service to Allow and choose Add to add it to the list of Allowed Services. The port this service uses will be unblocked.

    In case your service is not listed, you need to manually specify the port(s) to unblock. Choose Advanced to open a dialog where you can specify TCP, UPD, RPC ports and IP protocols. Refer to the help section in this dialog for details.

  4. Choose Next to display a summary of your changes. Modify them by choosing Back or apply them by choosing Finish.

15.4.2 Configuring Manually

The following paragraphs provide step-by-step instructions for a successful configuration. Each configuration item is marked whether it is relevant to firewalling or masquerading. Use port range (for example, 500:510) whenever appropriate. Aspects related to the DMZ (demilitarized zone) as mentioned in the configuration file are not covered here. They are applicable only to a more complex network infrastructure found in larger organizations (corporate networks), which require extensive configuration and in-depth knowledge about the subject.

To enable SuSEFirewall2, use sudo systemctl enable SuSEfirewall2 or use the YaST module Services Manager.

FW_DEV_EXT (firewall, masquerading)

The device linked to the Internet. For a modem connection, enter ppp0. DSL connections use dsl0. Specify auto to use the interface that corresponds to the default route.

FW_DEV_INT (firewall, masquerading)

The device linked to the internal, private network (such as eth0). Leave this blank if there is no internal network and the firewall protects only the host on which it runs.

FW_ROUTE (firewall, masquerading)

If you need the masquerading function, set this to yes. Your internal hosts will not be visible to the outside, because their private network addresses (for example 192.168.x.x) are ignored by Internet routers.

For a firewall without masquerading, set this to yes if you want to allow access to the internal network. Your internal hosts need to use officially registered IP addresses in this case. Normally, however, you should not allow access to your internal network from the outside.

FW_MASQUERADE (masquerading)

Set this to yes if you need the masquerading function. This provides a virtually direct connection to the Internet for the internal hosts. It is more secure to have a proxy server between the hosts of the internal network and the Internet. Masquerading is not needed for services that a proxy server provides.

FW_MASQ_NETS (masquerading)

Specify the hosts or networks to masquerade, leaving a space between the individual entries. For example:

FW_MASQ_NETS="192.168.0.0/24 192.168.10.1"
FW_PROTECT_FROM_INT (firewall)

Set this to yes to protect your firewall host from attacks originating in your internal network. Services are only available to the internal network if explicitly enabled. Also see FW_SERVICES_INT_TCP and FW_SERVICES_INT_UDP.

FW_SERVICES_EXT_TCP (firewall)

Enter the TCP ports that should be made available. Leave this blank for a normal workstation at home that should not offer any services.

FW_SERVICES_EXT_UDP (firewall)

Leave this blank unless you run a UDP service and want to make it available to the outside. The services that use UDP include DNS servers, IPsec, TFTP, DHCP and others. In that case, enter the UDP ports to use.

FW_SERVICES_ACCEPT_EXT (firewall)

List services to allow from the Internet. This is a more generic form of the FW_SERVICES_EXT_TCP and FW_SERVICES_EXT_UDP settings, and more specific than FW_TRUSTED_NETS. The notation is a space-separated list of NET,PROTOCOL[,DPORT][,SPORT], for example 0/0,tcp,22 or 0/0,tcp,22,,hitcount=3,blockseconds=60,recentname=ssh, which means: allow a maximum of three SSH connects per minute from one IP address.

FW_SERVICES_INT_TCP (firewall)

With this variable, define the services available for the internal network. The notation is the same as for FW_SERVICES_EXT_TCP, but the settings are applied to the internal network. The variable only needs to be set if FW_PROTECT_FROM_INT is set to yes.

FW_SERVICES_INT_UDP (firewall)

See FW_SERVICES_INT_TCP.

FW_SERVICES_ACCEPT_INT (firewall)

List services to allow from internal hosts. See FW_SERVICES_ACCEPT_EXT.

FW_SERVICES_ACCEPT_RELATED_* (firewall)

This is how the SuSEFirewall2 implementation considers packets RELATED by netfilter.

For example, to allow finer grained filtering of Samba broadcast packets, RELATED packets are not accepted unconditionally. Variables starting with FW_SERVICES_ACCEPT_RELATED_ allow restricting RELATED packets handling to certain networks, protocols and ports.

This means that adding connection tracking modules (conntrack modules) to FW_LOAD_MODULES does not automatically result in accepting the packets tagged by those modules. Additionally, you must set variables starting with FW_SERVICES_ACCEPT_RELATED_ to a suitable value.

FW_CUSTOMRULES (firewall)

Uncomment this variable to install custom rules. Find examples in /etc/sysconfig/scripts/SuSEfirewall2-custom.

After configuring the firewall, test your setup. The firewall rule sets are created by entering systemctl start SuSEfirewall2 as root. Then use telnet, for example, from an external host to see whether the connection is actually denied. After that, review the output of journalctl (see Chapter 15, journalctl: Query the systemd Journal), where you should see something like this:

Mar 15 13:21:38 linux kernel: SFW2-INext-DROP-DEFLT IN=eth0
OUT= MAC=00:80:c8:94:c3:e7:00:a0:c9:4d:27:56:08:00 SRC=192.168.10.0
DST=192.168.10.1 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=15330 DF PROTO=TCP
SPT=48091 DPT=23 WINDOW=5840 RES=0x00 SYN URGP=0
OPT (020405B40402080A061AFEBC0000000001030300)

Other packages to test your firewall setup are Nmap (portscanner) or OpenVAS (Open Vulnerability Assessment System). The documentation of Nmap is found at /usr/share/doc/packages/nmap after installing the package and the documentation of openVAS resides at http://www.openvas.org.

15.5 For More Information

The most up-to-date information and other documentation about the SuSEFirewall2 package is found in /usr/share/doc/packages/SuSEfirewall2. The home page of the netfilter and iptables project, http://www.netfilter.org, provides a large collection of documents in many languages.

16 Configuring a VPN Server

  • Filename: security_vpnserver.xml
  • ID: cha.security.vpnserver
Abstract

Today, Internet connections are cheap and available almost everywhere. However, not all connections are secure. Using a Virtual Private Network (VPN), you can create a secure network within an insecure network such as the Internet or Wi-Fi. It can be implemented in different ways and serves several purposes. In this chapter, we focus on the OpenVPN implementation to link branch offices via secure wide area networks (WANs).

16.1 Conceptual Overview

This section defines some terms regarding VPN and gives a brief overview of some scenarios.

16.1.1 Terminology

Endpoint

The two ends of a tunnel, the source or destination client.

Tap Device

A tap device simulates an Ethernet device (layer 2 packets in the OSI model, such as IP packets). A tap device is used for creating a network bridge. It works with Ethernet frames.

Tun Device

A tun device simulates a point-to-point network (layer 3 packets in the OSI model, such as Ethernet frames). A tun device is used with routing and works with IP frames.

Tunnel

Linking two locations through a primarily public network. From a more technical viewpoint, it is a connection between the client's device and the server's device. Usually a tunnel is encrypted, but it does need to be by definition.

16.1.2 VPN Scenarios

Whenever you set up a VPN connection, your IP packets are transferred over a secured tunnel. A tunnel can use either a tun or tap device. They are virtual network kernel drivers which implement the transmission of Ethernet frames or IP frames/packets.

Any user space program, such as OpenVPN, can attach itself to a tun or tap device to receive packets sent by your operating system. The program is also able to write packets to the device.

There are many solutions to set up and build a VPN connection. This section focuses on the OpenVPN package. Compared to other VPN software, OpenVPN can be operated in two modes:

Routed VPN

Routing is an easy solution to set up. It is more efficient and scales better than a bridged VPN. Furthermore, it allows the user to tune MTU (Maximum Transfer Unit) to raise efficiency. However, in a heterogeneous environment, if you do not have a Samba server on the gateway, NetBIOS broadcasts do not work. If you need IPv6, the drivers for the tun devices on both ends must support this protocol explicitly. This scenario is depicted in Figure 16.1, “Routed VPN”.

Routed VPN
Figure 16.1: Routed VPN
Bridged VPN

Bridging is a more complex solution. It is recommended when you need to browse Windows file shares across the VPN without setting up a Samba or WINS server. Bridged VPN is also needed to use non-IP protocols (such as IPX) or applications relying on network broadcasts. However, it is less efficient than routed VPN. Another disadvantage is that it does not scale well. This scenario is depicted in the following figures.

Bridged VPN - Scenario 1
Figure 16.2: Bridged VPN - Scenario 1
Bridged VPN - Scenario 2
Figure 16.3: Bridged VPN - Scenario 2
Bridged VPN - Scenario 3
Figure 16.4: Bridged VPN - Scenario 3

The major difference between bridging and routing is that a routed VPN cannot IP-broadcast while a bridged VPN can.

16.2 Setting Up a Simple Test Scenario

In the following example, we will create a point-to-point VPN tunnel. The example demonstrates how to create a VPN tunnel between one client and a server. It is assumed that your VPN server will use private IP addresses like IP_OF_SERVER and your client will use the IP address IP_OF_CLIENT. Make sure you select addresses which do not conflict with other IP addresses.

Warning
Warning: Use Only for Testing

This following scenario is provided as an example meant for familiarizing yourself with VPN technology. Do not use this as a real world scenario, as it can compromise the security and safety of your IT infrastructure!

Tip
Tip: Names for Configuration File

To simplify working with OpenVPN configuration files, we recommend the following:

  • Place your OpenVPN configuration files in the directory /etc/openvpn.

  • Name your configuration files MY_CONFIGURATION.conf.

  • If there are multiple files that belong to the same configuration, place them in a subdirectory like /etc/openvpn/MY_CONFIGURATION.

16.2.1 Configuring the VPN Server

To configure a VPN server, proceed as follows:

Procedure 16.1: VPN Server Configuration
  1. Install the package openvpn on the machine that will later become your VPN server.

  2. Open a shell, become root and create the VPN secret key:

    root # openvpn --genkey --secret /etc/openvpn/secret.key
  3. Copy the secret key to your client:

    root # scp /etc/openvpn/secret.key root@IP_OF_CLIENT:/etc/openvpn/
  4. Create the file /etc/openvpn/server.conf with the following content:

    dev tun
    ifconfig IP_OF_SERVER IP_OF_CLIENT
    secret secret.key
  5. Set up a tun device configuration by creating a file called /etc/sysconfig/network/ifcfg-tun0 with the following content:

    STARTMODE='manual'
    BOOTPROTO='static'
    TUNNEL='tun'
    TUNNEL_SET_OWNER='nobody'
    TUNNEL_SET_GROUP='nobody'
    LINK_REQUIRED=no
    PRE_UP_SCRIPT='systemd:openvpn@server'
    PRE_DOWN_SCRIPT='systemd:openvpn@service'

    The notation openvpn@server points to the OpenVPN server configuration file located at /etc/openvpn/server.conf. For more information, see /usr/share/doc/packages/openvpn/README.SUSE.

  6. If you use a firewall, start YaST and open UDP port 1194 (Security and Users › Firewall › Allowed Services).

  7. Start the OpenVPN server service by setting the tun device to up:

    tux > sudo wicked ifup tun0

    You should see the confirmation:

    tun0            up

16.2.2 Configuring the VPN Clients

To configure the VPN client, do the following:

Procedure 16.2: VPN Client Configuration
  1. Install the package openvpn on your client VPN machine.

  2. Create /etc/openvpn/client.conf with the following content:

    remote DOMAIN_OR_PUBLIC_IP_OF_SERVER
    dev tun
    ifconfig IP_OF_CLIENT IP_OF_SERVER
    secret secret.key

    Replace the placeholder IP_OF_CLIENT in the first line with either the domain name, or the public IP address of your server.

  3. Set up a tun device configuration by creating a file called /etc/sysconfig/network/ifcfg-tun0 with the following content:

    STARTMODE='manual'
    BOOTPROTO='static'
    TUNNEL='tun'
    TUNNEL_SET_OWNER='nobody'
    TUNNEL_SET_GROUP='nobody'
    LINK_REQUIRED=no
    PRE_UP_SCRIPT='systemd:openvpn@client'
    PRE_DOWN_SCRIPT='systemd:openvpn@client'
  4. If you use a firewall, start YaST and open UDP port 1194 as described in Step 6 of Procedure 16.1, “VPN Server Configuration”.

  5. Start the OpenVPN server service by setting the tun device to up:

    tux > sudo wicked ifup tun0

    You should see the confirmation:

    tun0            up

16.2.3 Testing the VPN Example Scenario

After OpenVPN has successfully started, test the availability of the tun device with the following command:

ip addr show tun0

To verify the VPN connection, use ping on both client and server side to see if they can reach each other. Ping the server from the client:

ping -I tun0 IP_OF_SERVER

Ping the client from the server:

ping -I tun0 IP_OF_CLIENT

16.3 Setting Up Your VPN Server Using a Certificate Authority

The example in Section 16.2 is useful for testing, but not for daily work. This section explains how to build a VPN server that allows more than one connection at the same time. This is done with a public key infrastructure (PKI). A PKI consists of a pair of public and private keys for the server and each client, and a master certificate authority (CA), which is used to sign every server and client certificate.

This setup involves the following basic steps:

16.3.1 Creating Certificates

Before a VPN connection can be established, the client must authenticate the server certificate. Conversely, the server must also authenticate the client certificate. This is called mutual authentication. To create such certificates, use the YaST CA module. See Chapter 17, Managing X.509 Certification for more details.

To create a VPN root, server, and client CA, proceed as follows:

Procedure 16.3: Creating a VPN Server Certificate
  1. Prepare a common VPN Certificate Authority (CA):

    1. Start the YaST CA module.

    2. Click Create Root CA.

    3. Enter a CA Name and a Common Name, for example VPN-Server-CA.

    4. Fill out the other boxes like e-mail addresses, organization, etc. and proceed with Next.

    5. Enter your password twice and proceed with Next.

    6. Review the summary. YaST displays the current settings for confirmation. Click Create. The root CA is created and displayed in the overview.

  2. Create a VPN server certificate:

    1. Select the root CA you created in Step 1 and click Enter CA.

    2. When prompted, enter the CA Password.

    3. Click the Certificate tab and click Add › Add Server Certificate.

    4. Specify a Common Name, for example, openvpn.example.com and proceed with Next.

    5. Specify your password and confirm it. Then click Advanced options.

      Switch to the Advanced Settings › Key Usage list and check one of the following sets:

      • digitalSignature and keyEncipherment, or,

      • digitalSignature and keyAgreement

      Switch to the Advanced Settings › extendedKeyUsage and type serverAuth for a server certificate.

      Important
      Important: Avoiding Man-in-the-Middle Attacks

      If you are using the method remote-cert-tls server or remote-cert-tls client to verify certificates, limit the number of times a key can be used. This mitigates man-in-the-middle attacks.

      For more information, see http://openvpn.net/index.php/open-source/documentation/howto.html#mitm.

      Finish with Ok and proceed with Next.

    6. Review the summary. YaST displays the current settings for confirmation. Click Create. When the VPN server certificate is created, it is displayed in the Certificates tab.

  3. Create VPN client certificates:

    1. Make sure you are on the Certificates tab.

    2. Click Add › Add Client Certificate.

    3. Enter a Common Name, for example, client1.example.com.

    4. Enter the e-mail addresses for your client, for example, user1@client1.example.com, and click Add. Proceed with Next.

    5. Enter your password twice and click Advanced options.

      Switch to Advanced Settings › Key Usage list and check one of the following flags:

      • digitalSignature or,

      • keyAgreement or,

      • digitalSignature and keyAgreement.

      Switch to the Advanced Settings › extendedKeyUsage and type clientAuth for a server certificate.

    6. Review the summary. YaST displays the current settings for confirmation. Click Create. The VPN client certificate is created and is displayed in the Certificates tab.

    7. If you need certificates for more clients, repeat Step 3.

After you have successfully finished Procedure 16.3, “Creating a VPN Server Certificate” you have a VPN root CA, a VPN server CA, and one or more VPN client CAs. To finish the task, proceed with the following procedure:

  1. Choose the Certificates tab.

  2. Export the VPN server certificate in two formats: PEM and unencrypted key in PEM.

    1. Select your VPN server certificate (openvpn.example.com in our example) and choose Export › Export to File.

    2. Select Only the Certificate in PEM Format, enter your VPN server certificate password and save the file to /etc/openvpn/server_crt.pem.

    3. Repeat Step 2.a and Step 2.b, but choose the format Only the Key Unencrypted in PEM Format. Save the file to /etc/openvpn/server_key.pem.

  3. Export the VPN client certificates and choose an export format, PEM or PKCS12 (preferred). For each client:

    1. Select your VPN client certificate (client1.example.com in our example) and choose Export › Export to File.

    2. Select Like PKCS12 and Include the CA Chain, enter your VPN client certificate key password and provide a PKCS12 password. Enter a File Name, click Browse and save the file to /etc/openvpn/client1.p12.

  4. Copy the files to your client (in our example, client1.example.com).

  5. Export the VPN CA (in our example VPN-Server-CA):

    1. Switch to the Description tab.

    2. Select Advanced › Export to File.

    3. Mark Only the Certificate in PEM Format and save the file to /etc/openvpn/vpn_ca.pem.

If desired, the client PKCS12 file can be converted into the PEM format using this command:

openssl pkcs12 -in client1.p12 -out client1.pem

Enter your client password to create the client1.pem file. The PEM file contains the client certificate, client key, and the CA certificate. You can split this combined file using a text editor and create three separate files. The file names can be used for the ca, cert, and key options in the OpenVPN configuration file (see Example 16.1, “VPN Server Configuration File”).

16.3.2 Configuring the VPN Server

As the basis of your configuration file, copy /usr/share/doc/packages/openvpn/sample-config-files/server.conf to /etc/openvpn/. Then customize it to your needs.

Example 16.1: VPN Server Configuration File
# /etc/openvpn/server.conf
port 1194 1
proto udp 2
dev tun0 3

# Security 4

ca    vpn_ca.pem
cert  server_crt.pem
key   server_key.pem

# ns-cert-type server 
remote-cert-tls client 5
dh   server/dh2048.pem 6

server 192.168.1.0 255.255.255.0 7
ifconfig-pool-persist /var/run/openvpn/ipp.txt 8

# Privileges 9
user nobody
group nobody

# Other configuration 10
keepalive 10 120
comp-lzo
persist-key
persist-tun
# status      /var/log/openvpn-status.tun0.log 11
# log-append  /var/log/openvpn-server.log 12
verb 4

1

The TCP/UDP port on which OpenVPN listens. You need to open the port in the firewall, see Chapter 15, Masquerading and Firewalls. The standard port for VPN is 1194, so you can usually leave that as it is.

2

The protocol, either UDP or TCP.

3

The tun or tap device. For the difference between these, see Section 16.1.1, “Terminology”.

4

The following lines contain the relative or absolute path to the root server CA certificate (ca), the root CA key (cert), and the private server key (key). These were generated in Section 16.3.1, “Creating Certificates”.

5

Require that peer certificates have been signed with an explicit key usage and extended key usage based on RFC3280 TLS rules. There is a description of how to make a server use this explicit key in Procedure 16.3, “Creating a VPN Server Certificate”.

6

The Diffie-Hellman parameters. Create the required file with the following command:

openssl dhparam -out /etc/openvpn/dh2048.pem 2048

7

Supplies a VPN subnet. The server can be reached by 192.168.1.1.

8

Records a mapping of clients and its virtual IP address in the given file. Useful when the server goes down and (after the restart) the clients get their previously assigned IP address.

9

For security reasons, run the OpenVPN daemon with reduced privileges. To do so, specify that it should use the group and user nobody.

10

Several other configuration options—see the comment in the example configuration file: /usr/share/doc/packages/openvpn/sample-config-files.

11

Enable this option to write short status updates with statistical data (operational status dump) to the named file. By default, this is not enabled.

All output is written to syslog. If you have more than one configuration file (for example, one for home and another for work), it is recommended to include the device name into the file name. This avoids overwriting output files accidentally. In this case, it is tun0, taken from the dev directive—see 3.

12

By default, log messages go to syslog. Overwrite this behavior by removing the hash character. In that case, all messages go to /var/log/openvpn-server.log. Do not forget to configure a logrotate service. See man 8 logrotate for further details.

After having completed this configuration, you can see log messages of your OpenVPN server under /var/log/openvpn.log. After having started it for the first time, it should finish with:

... Initialization Sequence Completed

If you do not see this message, check the log carefully for any hints of what is wrong in your configuration file.

16.3.3 Configuring the VPN Clients

As the basis of your configuration file, copy /usr/share/doc/packages/openvpn/sample-config-files/client.conf to /etc/openvpn/. Then customize it to your needs.

Example 16.2: VPN Client Configuration File
# /etc/openvpn/client.conf
client 1
dev tun 2
proto udp 3
remote IP_OR_HOST_NAME 1194 4
resolv-retry infinite
nobind

remote-cert-tls server 5

# Privileges 6
user nobody
group nobody

# Try to preserve some state across restarts.
persist-key
persist-tun

# Security 7
pkcs12 client1.p12

comp-lzo 8

1

Specifies that this machine is a client.

2

The network device. Both clients and server must use the same device.

3

The protocol. Use the same settings as on the server.

5

This is security option for clients which ensures that the host they connect to is a designated server.

4

Replace the placeholder IP_OR_HOST_NAME with the respective host name or IP address of your VPN server. After the host name, the port of the server is given. You can have multiple lines of remote entries pointing to different VPN servers. This is useful for load balancing between different VPN servers.

6

For security reasons, run the OpenVPN daemon with reduced privileges. To do so, specify that it should use the group and user nobody.

7

Contains the client files. For security reasons, use a separate pair of files for each client.

8

Turn on compression. Only use this parameter if compression is enabled on the server as well.

16.4 Setting Up a VPN Server or Client Using YaST

  • Filename: security_vpnserver_yast.xml
  • ID: sec.security.yastvpn

You can also use YaST to set up a VPN server. However, the YaST module does not support OpenVPN. Instead, it provides support for the IPsec protocol (as implemented in the software StrongSwan). Like OpenVPN, IPsec is a widely supported VPN scheme.

Procedure 16.4: Setting Up an IPsec Server
  1. To start the YaST VPN module, select Applications › VPN Gateways and Clients.

  2. Under Global Configuration, activate Enable VPN Daemon.

  3. To create a new VPN, click New VPN, then enter a name for the connection.

  4. Under Type, select Gateway (Server).

  5. Then choose the scenario:

    • The scenarios Secure communication with a pre-shared key and Secure communication with a certificate are best suited to Linux client setups.

    • The scenario Provide access to Android, iOS, Mac OS X clients sets up a configuration that is natively supported by modern versions of Android, iOS, and macOS. It is based on a pre-shared key setup with an additional user name and password authentication.

    • The scenario Provide access to Windows 7, Windows 8 clients is a configuration that is natively supported by Windows and BlackBerry devices. It is based on a certificate setup with an additional user name and password authentication.

    For this example, choose Secure communication with a pre-shared key.

  6. To specify the key, click Edit Credentials. Activate Show key, then type the secret key. Confirm with OK.

  7. Choose whether and how to limit access within your VPN under Provide VPN clients access to. To enable only certain IP ranges, specify these in CIDR format, separated by commas in Limited CIDRs. For more information about the CIDR format, see https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing.

  8. Under Clients' address pool, specify the format of IP addresses your VPN should provide to its clients.

  9. To finish, click OK. The YaST VPN module will now automatically add and enable firewall rules to allow clients to connect to the new VPN.

    To view the connection status, in the following confirmation window, click Yes. You will then see the output of systemctl status for your VPN, which allows you to check if the VPN is running and configured correctly.

16.5 For More Information

For more information about VPN in general, see:

  • http://www.openvpn.net: the OpenVPN home page

  • man openvpn

  • /usr/share/doc/packages/openvpn/sample-config-files/: example configuration files for different scenarios.

  • /usr/src/linux/Documentation/networking/tuntap.txt, to install the kernel-source package.

17 Managing X.509 Certification

  • Filename: security_yast2_ca.xml
  • ID: cha.security.yast_ca
Abstract

An increasing number of authentication mechanisms are based on cryptographic procedures. Digital certificates that assign cryptographic keys to their owners play an important role in this context. These certificates are used for communication and can also be found, for example, on company ID cards. The generation and administration of certificates is mostly handled by official institutions that offer this as a commercial service. In some cases, however, it may make sense to carry out these tasks yourself. For example, if a company does not want to pass personal data to third parties.

YaST provides two modules for certification, which offer basic management functions for digital X.509 certificates. The following sections explain the basics of digital certification and how to use YaST to create and administer certificates of this type.

17.1 The Principles of Digital Certification

Digital certification uses cryptographic processes to encrypt and protect data from access by unauthorized people. The user data is encrypted using a second data record, or key. The key is applied to the user data in a mathematical process, producing an altered data record in which the original content can no longer be identified. Asymmetrical encryption is now in general use (public key method). Keys always occur in pairs:

Private Key

The private key must be kept safely by the key owner. Accidental publication of the private key compromises the key pair and renders it useless.

Public Key

The key owner circulates the public key for use by third parties.

17.1.1 Key Authenticity

Because the public key process is in widespread use, there are many public keys in circulation. Successful use of this system requires that every user be sure that a public key actually belongs to the assumed owner. The assignment of users to public keys is confirmed by trustworthy organizations with public key certificates. Such certificates contain the name of the key owner, the corresponding public key, and the electronic signature of the person issuing the certificate.

Trustworthy organizations that issue and sign public key certificates are usually part of a certification infrastructure. This is responsible for the other aspects of certificate management, such as publication, withdrawal, and renewal of certificates. An infrastructure of this kind is generally called a public key infrastructure or PKI. One familiar PKI is the OpenPGP standard in which users publish their certificates themselves without central authorization points. These certificates become trustworthy when signed by other parties in the web of trust.

The X.509 Public Key Infrastructure (PKIX) is an alternative model defined by the IETF (Internet Engineering Task Force) that serves as a model for almost all publicly-used PKIs today. In this model, authentication is made by certificate authorities (CA) in a hierarchical tree structure. The root of the tree is the root CA, which certifies all sub-CAs. The lowest level of sub-CAs issue user certificates. The user certificates are trustworthy by certification that can be traced to the root CA.

The security of such a PKI depends on the trustworthiness of the CA certificates. To make certification practices clear to PKI customers, the PKI operator defines a certification practice statement (CPS) that defines the procedures for certificate management. This should ensure that the PKI only issues trustworthy certificates.

17.1.2 X.509 Certificates

An X.509 certificate is a data structure with several fixed fields and, optionally, additional extensions. The fixed fields mainly contain the name of the key owner, the public key, and the data relating to the issuing CA (name and signature). For security reasons, a certificate should only have a limited period of validity, so a field is also provided for this date. The CA guarantees the validity of the certificate in the specified period. The CPS usually requires the PKI (the issuing CA) to create and distribute a new certificate before expiration.

The extensions can contain any additional information. An application is only required to be able to evaluate an extension if it is identified as critical. If an application does not recognize a critical extension, it must reject the certificate. Some extensions are only useful for a specific application, such as signature or encryption.

Table 17.1 shows the fields of a basic X.509 certificate in version 3.

Table 17.1: X.509v3 Certificate

Field

Content

Version

The version of the certificate, for example, v3

Serial Number

Unique certificate ID (an integer)

Signature

The ID of the algorithm used to sign the certificate

Issuer

Unique name (DN) of the issuing authority (CA)

Validity

Period of validity

Subject

Unique name (DN) of the owner

Subject Public Key Info

Public key of the owner and the ID of the algorithm

Issuer Unique ID

Unique ID of the issuing CA (optional)

Subject Unique ID

Unique ID of the owner (optional)

Extensions

Optional additional information, such as KeyUsage or BasicConstraints

17.1.3 Blocking X.509 Certificates

If a certificate becomes untrustworthy before it has expired, it must be blocked immediately. This can become necessary if, for example, the private key has accidentally been made public. Blocking certificates is especially important if the private key belongs to a CA rather than a user certificate. In this case, all user certificates issued by the relevant CA must be blocked immediately. If a certificate is blocked, the PKI (the responsible CA) must make this information available to all those involved using a certificate revocation list (CRL).

These lists are supplied by the CA to public CRL distribution points (CDPs) at regular intervals. The CDP can optionally be named as an extension in the certificate, so a checker can fetch a current CRL for validation purposes. One way to do this is the online certificate status protocol (OCSP). The authenticity of the CRLs is ensured with the signature of the issuing CA. Table 17.2 shows the basic parts of a X.509 CRL.

Table 17.2: X.509 Certificate Revocation List (CRL)

Field

Content

Version

The version of the CRL, such as v2

Signature

The ID of the algorithm used to sign the CRL

Issuer

Unique name (DN) of the publisher of the CRL (usually the issuing CA)

This Update

Time of publication (date, time) of this CRL

Next Update

Time of publication (date, time) of the next CRL

List of revoked certificates

Every entry contains the serial number of the certificate, the time of revocation, and optional extensions (CRL entry extensions)

Extensions

Optional CRL extensions

17.1.4 Repository for Certificates and CRLs

The certificates and CRLs for a CA must be made publicly accessible using a repository. Because the signature protects the certificates and CRLs from being forged, the repository itself does not need to be secured in a special way. Instead, it tries to grant the simplest and fastest access possible. For this reason, certificates are often provided on an LDAP or HTTP server. Find explanations about LDAP in Chapter 5, LDAP—A Directory Service. Chapter 31, The Apache HTTP Server contains information about the HTTP server.

17.1.5 Proprietary PKI

YaST contains modules for the basic management of X.509 certificates. This mainly involves the creation of CAs, sub-CAs, and their certificates. The services of a PKI go far beyond simply creating and distributing certificates and CRLs. The operation of a PKI requires a well-conceived administrative infrastructure allowing continuous update of certificates and CRLs. This infrastructure is provided by commercial PKI products and can also be partly automated. YaST provides tools for creating and distributing CAs and certificates, but cannot currently offer this background infrastructure. To set up a small PKI, you can use the available YaST modules. However, you should use commercial products to set up an official or commercial PKI.

17.2 YaST Modules for CA Management

YaST provides two modules for basic CA management. The primary management tasks with these modules are explained here.

17.2.1 Creating a Root CA

After a default installation, SUSE Linux Enterprise Server contains already a root CA named YaST_Default_CA. Use this module to create additional root CAs. The first step when setting up a PKI is to create a root CA. Do the following:

  1. Start YaST and go to Security and Users › CA Management.

  2. Click Create Root CA.

  3. Enter the basic data for the CA in the first dialog, shown in Figure 17.1. The text boxes have the following meanings:

    YaST CA Module—Basic Data for a Root CA
    Figure 17.1: YaST CA Module—Basic Data for a Root CA
    CA Name

    Enter the technical name of the CA. Directory names, among other things, are derived from this name, which is why only the characters listed in the help can be used. The technical name is also displayed in the overview when the module is started.

    Common Name

    Enter the name for use in referring to the CA.

    E-Mail Addresses

    Several e-mail addresses can be entered that can be seen by the CA user. This can be helpful for inquiries.

    Country

    Select the country where the CA is operated.

    Organization, Organizational Unit, Locality, State

    Optional values

    Proceed with Next.

  4. Enter a password in the second dialog. This password is always required when using the CA—when creating a sub-CA or generating certificates. The text boxes have the following meaning:

    Key Length

    Key Length contains a meaningful default and does not generally need to be changed unless an application cannot deal with this key length. The higher the number the more secure your password is.

    Valid Period (days)

    The Valid Period in the case of a CA defaults to 3650 days (roughly ten years). This long period makes sense because the replacement of a deleted CA involves an enormous administrative effort.

    Clicking Advanced Options opens a dialog for setting different attributes from the X.509 extensions (Figure 17.4, “YaST CA Module—Extended Settings”). These values have rational default settings and should only be changed if you are really sure of what you are doing. Proceed with Next.

  5. Review the summary. YaST displays the current settings for confirmation. Click Create. The root CA is created then appears in the overview.

Tip
Tip

In general, it is best not to allow user certificates to be issued by the root CA. It is better to create at least one sub-CA and create the user certificates from there. This has the advantage that the root CA can be kept isolated and secure, for example, on an isolated computer on secure premises. This makes it very difficult to attack the root CA.

17.2.2 Changing Password

If you need to change your password for your CA, proceed as follows:

  1. Start YaST and open the CA module.

  2. Select the required root CA and click Enter CA.

  3. Enter the password if you entered a CA the first time. YaST displays the CA key information in the Description tab (see Figure 17.2).

  4. Click Advanced and select Change CA Password. A dialog opens.

  5. Enter the old and the new password.

  6. Finish with OK

17.2.3 Creating or Revoking a Sub-CA

A sub-CA is created in the same way as a root CA.

Note
Note

The validity period for a sub-CA must be fully within the validity period of the parent CA. A sub-CA is always created after the parent CA, therefore, the default value leads to an error message. To avoid this, enter a permissible value for the period of validity.

Do the following:

  1. Start YaST and open the CA module.

  2. Select the required root CA and click Enter CA.

  3. Enter the password if you are entering a CA for the first time. YaST displays the CA key information in the tab Description (see Figure 17.2).

    YaST CA Module—Using a CA
    Figure 17.2: YaST CA Module—Using a CA
  4. Click Advanced and select Create SubCA. This opens the same dialog as for creating a root CA.

  5. Proceed as described in Section 17.2.1, “Creating a Root CA”.

    It is possible to use one password for all your CAs. Enable Use CA Password as Certificate Password to give your sub-CAs the same password as your root CA. This helps to reduce the amount of passwords for your CAs.

    Note
    Note: Check your Valid Period

    Take into account that the valid period must be lower than the valid period in the root CA.

  6. Select the Certificates tab. Reset compromised or otherwise unwanted sub-CAs here, using Revoke. Revocation alone is not enough to deactivate a sub-CA. You must also publish revoked sub-CAs in a CRL. The creation of CRLs is described in Section 17.2.6, “Creating Certificate Revocation Lists (CRLs)”.

  7. Finish with OK.

17.2.4 Creating or Revoking User Certificates

Creating client and server certificates is very similar to creating CAs in Section 17.2.1, “Creating a Root CA”. The same principles apply here. In certificates intended for e-mail signature, the e-mail address of the sender (the private key owner) should be contained in the certificate to enable the e-mail program to assign the correct certificate.

For certificate assignment during encryption, it is necessary for the e-mail address of the recipient (the public key owner) to be included in the certificate. In the case of server and client certificates, the host name of the server must be entered in the Common Name field. The default validity period for certificates is 365 days.

To create client and server certificates, do the following:

  1. Start YaST and open the CA module.

  2. Select the required root CA and click Enter CA.

  3. Enter the password if you are entering a CA for the first time. YaST displays the CA key information in the Description tab.

  4. Click Certificates (see Figure 17.3).

    Certificates of a CA
    Figure 17.3: Certificates of a CA
  5. Click Add › Add Server Certificate and create a server certificate.

  6. Click Add › Add Client Certificate and create a client certificate. Do not forget to enter an e-mail address.

  7. Finish with OK

To revoke compromised or otherwise unwanted certificates, do the following:

  1. Start YaST and open the CA module.

  2. Select the required root CA and click Enter CA.

  3. Enter the password if you are entering a CA for the first time. YaST displays the CA key information in the Description tab.

  4. Click Certificates (see Section 17.2.3, “Creating or Revoking a Sub-CA”).

  5. Select the certificate to revoke and click Revoke.

  6. Choose a reason to revoke this certificate.

  7. Finish with OK.

Note
Note

Revocation alone is not enough to deactivate a certificate. Also publish revoked certificates in a CRL. Section 17.2.6, “Creating Certificate Revocation Lists (CRLs)” explains how to create CRLs. Revoked certificates can be completely removed after publication in a CRL with Delete.

17.2.5 Changing Default Values

The previous sections explained how to create sub-CAs, client certificates, and server certificates. Special settings are used in the extensions of the X.509 certificate. These settings have been given rational defaults for every certificate type and do not normally need to be changed. However, it may be that you have special requirements for these extensions. In this case, it may make sense to adjust the defaults. Otherwise, start from scratch every time you create a certificate.

  1. Start YaST and open the CA module.

  2. Enter the required root CA, as described in Section 17.2.3, “Creating or Revoking a Sub-CA”.

  3. Click Advanced › Edit Default.

  4. Choose type of certificate to change and proceed with Next.

  5. The dialog for changing the defaults as shown in Figure 17.4, “YaST CA Module—Extended Settings” opens.

    YaST CA Module—Extended Settings
    Figure 17.4: YaST CA Module—Extended Settings
  6. Change the associated value on the right side and set or delete the critical setting with critical.

  7. Click Next to see a short summary.

  8. Finish your changes with Save.

Note
Note

All changes to the defaults only affect objects created after this point. Already-existing CAs and certificates remain unchanged.

17.2.6 Creating Certificate Revocation Lists (CRLs)

If compromised or otherwise unwanted certificates need to be excluded from further use, they must first be revoked. The procedure for this is explained in Section 17.2.3, “Creating or Revoking a Sub-CA” (for sub-CAs) and Section 17.2.4, “Creating or Revoking User Certificates” (for user certificates). After this, a CRL must be created and published with this information.

The system maintains only one CRL for each CA. To create or update this CRL, do the following:

  1. Start YaST and open the CA module.

  2. Enter the required CA, as described in Section 17.2.3, “Creating or Revoking a Sub-CA”.

  3. Click CRL. The dialog that opens displays a summary of the last CRL of this CA.

  4. Create a new CRL with Generate CRL if you have revoked new sub-CAs or certificates since its creation.

  5. Specify the period of validity for the new CRL (default: 30 days).

  6. Click OK to create and display the CRL. Afterward, you must publish this CRL.

Note
Note

Applications that evaluate CRLs reject every certificate if the CRL is not available or has expired. As a PKI provider, it is your duty always to create and publish a new CRL before the current CRL expires (period of validity). YaST does not provide a function for automating this procedure.

17.2.7 Exporting CA Objects to LDAP

The executing computer should be configured with the YaST LDAP client for LDAP export. This provides LDAP server information at runtime that can be used when completing dialog fields. Otherwise (although export may be possible), all LDAP data must be entered manually. You must always enter several passwords (see Table 17.3, “Passwords during LDAP Export”).

Table 17.3: Passwords during LDAP Export

Password

Meaning

LDAP Password

Authorizes the user to make entries in the LDAP tree.

Certificate Password

Authorizes the user to export the certificate.

New Certificate Password

The PKCS12 format is used during LDAP export. This format forces the assignment of a new password for the exported certificate.

Certificates, CAs, and CRLs can be exported to LDAP.

Exporting a CA to LDAP

To export a CA, enter the CA as described in Section 17.2.3, “Creating or Revoking a Sub-CA”. Select Extended › Export to LDAP in the subsequent dialog, which opens the dialog for entering LDAP data. If your system has been configured with the YaST LDAP client, the fields are already partly completed. Otherwise, enter all the data manually. Entries are made in LDAP in a separate tree with the attribute caCertificate.

Exporting a Certificate to LDAP

Enter the CA containing the certificate to export then select Certificates. Select the required certificate from the certificate list in the upper part of the dialog and select Export › Export to LDAP. The LDAP data is entered here in the same way as for CAs. The certificate is saved with the corresponding user object in the LDAP tree with the attributes userCertificate (PEM format) and userPKCS12 (PKCS12 format).

Exporting a CRL to LDAP

Enter the CA containing the CRL to export and select CRL. If desired, create a new CRL and click Export. The dialog that opens displays the export parameters. You can export the CRL for this CA either once or in periodical time intervals. Activate the export by selecting Export to LDAP and enter the respective LDAP data. To do this at regular intervals, select the Repeated Recreation and Export radio button and change the interval, if appropriate.

17.2.8 Exporting CA Objects as a File

If you have set up a repository on the computer for administering CAs, you can use this option to create the CA objects directly as a file at the correct location. Different output formats are available, such as PEM, DER, and PKCS12. In the case of PEM, it is also possible to choose whether a certificate should be exported with or without key and whether the key should be encrypted. In the case of PKCS12, it is also possible to export the certification path.

Export a file in the same way for certificates, CAs as with LDAP, described in Section 17.2.7, “Exporting CA Objects to LDAP”, except you should select Export as File instead of Export to LDAP. This then takes you to a dialog for selecting the required output format and entering the password and file name. The certificate is stored at the required location after clicking OK.

For CRLs click Export, select Export to file, choose the export format (PEM or DER) and enter the path. Proceed with OK to save it to the respective location.

Tip
Tip

You can select any storage location in the file system. This option can also be used to save CA objects on a transport medium, such as a flash disk. The /media directory generally holds any type of drive except the hard disk of your system.

17.2.9 Importing Common Server Certificates

If you have exported a server certificate with YaST to your media on an isolated CA management computer, you can import this certificate on a server as a common server certificate. Do this during installation or at a later point with YaST.

Note
Note

You need one of the PKCS12 formats to import your certificate successfully.

The general server certificate is stored in /etc/ssl/servercerts and can be used there by any CA-supported service. When this certificate expires, it can easily be replaced using the same mechanisms. To get things functioning with the replaced certificate, restart the participating services.

Tip
Tip

If you select Import here, you can select the source in the file system. This option can also be used to import certificates from removable media, such as a flash disk.

To import a common server certificate, do the following:

  1. Start YaST and open Common Server Certificate under Security and Users

  2. View the data for the current certificate in the description field after YaST has been started.

  3. Select Import and the certificate file.

  4. Enter the password and click Next. The certificate is imported then displayed in the description field.

  5. Close YaST with Finish.

Part IV Confining Privileges with AppArmor

18 Introducing AppArmor

Many security vulnerabilities result from bugs in trusted programs. A trusted program runs with privileges that attackers want to possess. The program fails to keep that trust if there is a bug in the program that allows the attacker to acquire said privilege.

19 Getting Started

Prepare a successful deployment of AppArmor on your system by carefully considering the following items:

20 Immunizing Programs

Effective hardening of a computer system requires minimizing the number of programs that mediate privilege, then securing the programs as much as possible. With AppArmor, you only need to profile the programs that are exposed to attack in your environment, which drastically reduces the amount of wor…

21 Profile Components and Syntax

Building AppArmor profiles to confine an application is very straightforward and intuitive. AppArmor ships with several tools that assist in profile creation. It does not require you to do any programming or script handling. The only task that is required of the administrator is to determine a polic…

22 AppArmor Profile Repositories

AppArmor ships with a set of profiles enabled by default. These are created by the AppArmor developers, and are stored in /etc/apparmor.d. In addition to these profiles, SUSE Linux Enterprise Server ships profiles for individual applications together with the relevant application. These profiles are…

23 Building and Managing Profiles with YaST

YaST provides a basic way to build profiles and manage AppArmor® profiles. It provides two interfaces: a graphical one and a text-based one. The text-based interface consumes less resources and bandwidth, making it a better choice for remote administration, or for times when a local graphical enviro…

24 Building Profiles from the Command Line

AppArmor® provides the user the ability to use a command line interface rather than a graphical interface to manage and configure the system security. Track the status of AppArmor and create, delete, or modify AppArmor profiles using the AppArmor command line tools.

25 Profiling Your Web Applications Using ChangeHat

An AppArmor® profile represents the security policy for an individual program instance or process. It applies to an executable program, but if a portion of the program needs different access permissions than other portions, the program can “change hats” to use a different security context, distincti…

26 Confining Users with pam_apparmor

An AppArmor profile applies to an executable program; if a portion of the program needs different access permissions than other portions need, the program can change hats via change_hat to a different role, also known as a subprofile. The pam_apparmor PAM module allows applications to confine authen…

27 Managing Profiled Applications

After creating profiles and immunizing your applications, SUSE® Linux Enterprise Server becomes more efficient and better protected as long as you perform AppArmor® profile maintenance (which involves analyzing log files, refining your profiles, backing up your set of profiles and keeping it up-to-d…

28 Support

This chapter outlines maintenance-related tasks. Learn how to update AppArmor® and get a list of available man pages providing basic help for using the command line tools provided by AppArmor. Use the troubleshooting section to learn about some common problems encountered with AppArmor and their sol…

29 AppArmor Glossary

18 Introducing AppArmor

  • Filename: apparmor_intro.xml
  • ID: cha.apparmor.intro

Many security vulnerabilities result from bugs in trusted programs. A trusted program runs with privileges that attackers want to possess. The program fails to keep that trust if there is a bug in the program that allows the attacker to acquire said privilege.

AppArmor® is an application security solution designed specifically to apply privilege confinement to suspect programs. AppArmor allows the administrator to specify the domain of activities the program can perform by developing a security profile. A security profile is a listing of files that the program may access and the operations the program may perform. AppArmor secures applications by enforcing good application behavior without relying on attack signatures, so it can prevent attacks even if previously unknown vulnerabilities are being exploited.

18.1 AppArmor Components

AppArmor consists of:

  • A library of AppArmor profiles for common Linux* applications, describing what files the program needs to access.

  • A library of AppArmor profile foundation classes (profile building blocks) needed for common application activities, such as DNS lookup and user authentication.

  • A tool suite for developing and enhancing AppArmor profiles, so that you can change the existing profiles to suit your needs and create new profiles for your own local and custom applications.

  • Several specially modified applications that are AppArmor enabled to provide enhanced security in the form of unique subprocess confinement (including Apache).

  • The AppArmor-related kernel code and associated control scripts to enforce AppArmor policies on your SUSE® Linux Enterprise Server system.

18.2 Background Information on AppArmor Profiling

For more information about the science and security of AppArmor, refer to the following papers:

SubDomain: Parsimonious Server Security by Crispin Cowan, Steve Beattie, Greg Kroah-Hartman, Calton Pu, Perry Wagle, and Virgil Gligor

Describes the initial design and implementation of AppArmor. Published in the proceedings of the USENIX LISA Conference, December 2000, New Orleans, LA. This paper is now out of date, describing syntax and features that are different from the current AppArmor product. This paper should be used only for background, and not for technical documentation.

Defcon Capture the Flag: Defending Vulnerable Code from Intense Attack by Crispin Cowan, Seth Arnold, Steve Beattie, Chris Wright, and John Viega

A good guide to strategic and tactical use of AppArmor to solve severe security problems in a very short period of time. Published in the Proceedings of the DARPA Information Survivability Conference and Expo (DISCEX III), April 2003, Washington, DC.

AppArmor for Geeks by Seth Arnold

This document tries to convey a better understanding of the technical details of AppArmor. It is available at http://en.opensuse.org/SDB:AppArmor_geeks.

19 Getting Started

  • Filename: apparmor_start.xml
  • ID: cha.apparmor.start

Prepare a successful deployment of AppArmor on your system by carefully considering the following items:

  1. Determine the applications to profile. Read more on this in Section 19.3, “Choosing Applications to Profile”.

  2. Build the needed profiles as roughly outlined in Section 19.4, “Building and Modifying Profiles”. Check the results and adjust the profiles when necessary.

  3. Update your profiles whenever your environment changes or you need to react to security events logged by the reporting tool of AppArmor. Refer to Section 19.5, “Updating Your Profiles”.

19.1 Installing AppArmor

AppArmor is installed and running on any installation of SUSE® Linux Enterprise Server by default, regardless of what patterns are installed. The packages listed below are needed for a fully-functional instance of AppArmor:

  • apparmor-docs

  • apparmor-parser

  • apparmor-profiles

  • apparmor-utils

  • audit

  • libapparmor1

  • perl-libapparmor

  • yast2-apparmor

Tip
Tip

If AppArmor is not installed on your system, install the pattern apparmor for a complete AppArmor installation. Either use the YaST Software Management module for installation, or use Zypper on the command line:

zypper in -t pattern apparmor

19.2 Enabling and Disabling AppArmor

AppArmor is configured to run by default on any fresh installation of SUSE Linux Enterprise Server. There are two ways of toggling the status of AppArmor:

Using YaST Services Manager

Disable or enable AppArmor by removing or adding its boot script to the sequence of scripts executed on system boot. Status changes are applied on reboot.

Using AppArmor Configuration Window

Toggle the status of AppArmor in a running system by switching it off or on using the YaST AppArmor Control Panel. Changes made here are applied instantaneously. The Control Panel triggers a stop or start event for AppArmor and removes or adds its boot script in the system's boot sequence.

To disable AppArmor permanently (by removing it from the sequence of scripts executed on system boot) proceed as follows:

  1. Start YaST.

  2. Select System › Services Manager.

  3. Mark apparmor by clicking its row in the list of services, then click Enable/Disable in the lower part of the window. Check that Enabled changed to Disabled in the apparmor row.

  4. Confirm with OK.

AppArmor will not be initialized on reboot, and stays inactive until you re-enable it. Re-enabling a service using the YaST Services Manager tool is similar to disabling it.

Toggle the status of AppArmor in a running system by using the AppArmor Configuration window. These changes take effect when you apply them and survive a reboot of the system. To toggle the status of AppArmor, proceed as follows:

  1. Start YaST, select AppArmor Configuration, and click Settings in the main window.

  2. Enable AppArmor by checking Enable AppArmor or disable AppArmor by deselecting it.

  3. Click Done in the AppArmor Configuration window.

19.3 Choosing Applications to Profile

You only need to protect the programs that are exposed to attacks in your particular setup, so only use profiles for those applications you actually run. Use the following list to determine the most likely candidates:

Network Agents
Web Applications
Cron Jobs

To find out which processes are currently running with open network ports and might need a profile to confine them, run aa-unconfined as root.

Example 19.1: Output of aa-unconfined
19848 /usr/sbin/cupsd not confined
19887 /usr/sbin/sshd not confined
19947 /usr/lib/postfix/master not confined
1328 /usr/sbin/ntpd confined by '/usr/sbin/ntpd (enforce)'

Each of the processes in the above example labeled not confined might need a custom profile to confine it. Those labeled confined by are already protected by AppArmor.

Tip
Tip: For More Information

For more information about choosing the right applications to profile, refer to Section 20.2, “Determining Programs to Immunize”.

19.4 Building and Modifying Profiles

AppArmor on SUSE Linux Enterprise Server ships with a preconfigured set of profiles for the most important applications. In addition, you can use AppArmor to create your own profiles for any application you want.

There are two ways of managing profiles. One is to use the graphical front-end provided by the YaST AppArmor modules and the other is to use the command line tools provided by the AppArmor suite itself. The main difference is that YaST supports only basic functionality for AppArmor profiles, while the command line tools let you update/tune the profiles in a more fine-grained way.

For each application, perform the following steps to create a profile:

  1. As root, let AppArmor create a rough outline of the application's profile by running aa-genprof PROGRAM_NAME.

    or

    Outline the basic profile by running YaST › Security and Users › AppArmor Configuration › Manually Add Profile and specifying the complete path to the application you want to profile.

    A new basic profile is outlined and put into learning mode, which means that it logs any activity of the program you are executing, but does not yet restrict it.

  2. Run the full range of the application's actions to let AppArmor get a very specific picture of its activities.

  3. Let AppArmor analyze the log files generated in Step 2 by typing S in aa-genprof.

    AppArmor scans the logs it recorded during the application's run and asks you to set the access rights for each event that was logged. Either set them for each file or use globbing.

  4. Depending on the complexity of your application, it might be necessary to repeat Step 2 and Step 3. Confine the application, exercise it under the confined conditions, and process any new log events. To properly confine the full range of an application's capabilities, you might be required to repeat this procedure often.

  5. When you finish aa-genprof, your profile is set to enforce mode. The profile is applied and AppArmor restricts the application according to it.

    If you started aa-genprof on an application that had an existing profile that was in complain mode, this profile remains in learning mode upon exit of this learning cycle. For more information about changing the mode of a profile, refer to Section 24.7.3.2, “aa-complain—Entering Complain or Learning Mode” and Section 24.7.3.6, “aa-enforce—Entering Enforce Mode”.

Test your profile settings by performing every task you need with the application you confined. Normally, the confined program runs smoothly and you do not notice AppArmor activities. However, if you notice certain misbehavior with your application, check the system logs and see if AppArmor is too tightly confining your application. Depending on the log mechanism used on your system, there are several places to look for AppArmor log entries:

/var/log/audit/audit.log
The command journalctl | grep -i apparmor
The command dmesg -T

To adjust the profile, analyze the log messages relating to this application again as described in Section 24.7.3.9, “aa-logprof—Scanning the System Log”. Determine the access rights or restrictions when prompted.

Tip
Tip: For More Information

For more information about profile building and modification, refer to Chapter 21, Profile Components and Syntax, Chapter 23, Building and Managing Profiles with YaST, and Chapter 24, Building Profiles from the Command Line.

19.5 Updating Your Profiles

Software and system configurations change over time. As a result, your profile setup for AppArmor might need some fine-tuning from time to time. AppArmor checks your system log for policy violations or other AppArmor events and lets you adjust your profile set accordingly. Any application behavior that is outside of any profile definition can be addressed by aa-logprof. For more information, see Section 24.7.3.9, “aa-logprof—Scanning the System Log”.

20 Immunizing Programs

  • Filename: apparmor_whatimmunize.xml
  • ID: cha.apparmor.concept

Effective hardening of a computer system requires minimizing the number of programs that mediate privilege, then securing the programs as much as possible. With AppArmor, you only need to profile the programs that are exposed to attack in your environment, which drastically reduces the amount of work required to harden your computer. AppArmor profiles enforce policies to make sure that programs do what they are supposed to do, but nothing else.

AppArmor provides immunization technologies that protect applications from the inherent vulnerabilities they possess. After installing AppArmor, setting up AppArmor profiles, and rebooting the computer, your system becomes immunized because it begins to enforce the AppArmor security policies. Protecting programs with AppArmor is called immunizing.

Administrators need only concern themselves with the applications that are vulnerable to attacks, and generate profiles for these. Hardening a system thus comes down to building and maintaining the AppArmor profile set and monitoring any policy violations or exceptions logged by AppArmor's reporting facility.

Users should not notice AppArmor. It runs behind the scenes and does not require any user interaction. Performance is not noticeably affected by AppArmor. If some activity of the application is not covered by an AppArmor profile or if some activity of the application is prevented by AppArmor, the administrator needs to adjust the profile of this application.

AppArmor sets up a collection of default application profiles to protect standard Linux services. To protect other applications, use the AppArmor tools to create profiles for the applications that you want protected. This chapter introduces the philosophy of immunizing programs. Proceed to Chapter 21, Profile Components and Syntax, Chapter 23, Building and Managing Profiles with YaST, or Chapter 24, Building Profiles from the Command Line if you are ready to build and manage AppArmor profiles.

AppArmor provides streamlined access control for network services by specifying which files each program is allowed to read, write, and execute, and which type of network it is allowed to access. This ensures that each program does what it is supposed to do, and nothing else. AppArmor quarantines programs to protect the rest of the system from being damaged by a compromised process.

AppArmor is a host intrusion prevention or mandatory access control scheme. Previously, access control schemes were centered around users because they were built for large timeshare systems. Alternatively, modern network servers largely do not permit users to log in, but instead provide a variety of network services for users (such as Web, mail, file, and print servers). AppArmor controls the access given to network services and other programs to prevent weaknesses from being exploited.

Tip
Tip: Background Information for AppArmor

To get a more in-depth overview of AppArmor and the overall concept behind it, refer to Section 18.2, “Background Information on AppArmor Profiling”.

20.1 Introducing the AppArmor Framework

This section provides a very basic understanding of what is happening behind the scenes (and under the hood of the YaST interface) when you run AppArmor.

An AppArmor profile is a plain text file containing path entries and access permissions. See Section 21.1, “Breaking an AppArmor Profile into Its Parts” for a detailed reference profile. The directives contained in this text file are then enforced by the AppArmor routines to quarantine the process or program.

The following tools interact in the building and enforcement of AppArmor profiles and policies:

aa-status

aa-status reports various aspects of the current state of the running AppArmor confinement.

aa-unconfined

aa-unconfined detects any application running on your system that listens for network connections and is not protected by an AppArmor profile. Refer to Section 24.7.3.12, “aa-unconfined—Identifying Unprotected Processes” for detailed information about this tool.

aa-autodep

aa-autodep creates a basic framework of a profile that needs to be fleshed out before it is put to use in production. The resulting profile is loaded and put into complain mode, reporting any behavior of the application that is not (yet) covered by AppArmor rules. Refer to Section 24.7.3.1, “aa-autodep—Creating Approximate Profiles” for detailed information about this tool.

aa-genprof

aa-genprof generates a basic profile and asks you to refine this profile by executing the application and generating log events that need to be taken care of by AppArmor policies. You are guided through a series of questions to deal with the log events that have been triggered during the application's execution. After the profile has been generated, it is loaded and put into enforce mode. Refer to Section 24.7.3.8, “aa-genprof—Generating Profiles” for detailed information about this tool.

aa-logprof

aa-logprof interactively scans and reviews the log entries generated by an application that is confined by an AppArmor profile in both complain and enforced modes. It assists you in generating new entries in the profile concerned. Refer to Section 24.7.3.9, “aa-logprof—Scanning the System Log” for detailed information about this tool.

aa-easyprof

aa-easyprof provides an easy-to-use interface for AppArmor profile generation. aa-easyprof supports the use of templates and policy groups to quickly profile an application. Note that while this tool can help with policy generation, its utility is dependent on the quality of the templates, policy groups and abstractions used. aa-easyprof may create a profile that is less restricted than creating the profile with aa-genprof and aa-logprof.

aa-complain

aa-complain toggles the mode of an AppArmor profile from enforce to complain. Violations to rules set in a profile are logged, but the profile is not enforced. Refer to Section 24.7.3.2, “aa-complain—Entering Complain or Learning Mode” for detailed information about this tool.

aa-enforce

aa-enforce toggles the mode of an AppArmor profile from complain to enforce. Violations to rules set in a profile are logged and not permitted—the profile is enforced. Refer to Section 24.7.3.6, “aa-enforce—Entering Enforce Mode” for detailed information about this tool.

aa-disable

aa-disable disables the enforcement mode for one or more AppArmor profiles. This command will unload the profile from the kernel and prevent it from being loaded on AppArmor start-up. The aa-enforce and aa-complain utilities may be used to change this behavior.

aa-exec

aa-exec launches a program confined by the specified AppArmor profile and/or namespace. If both a profile and namespace are specified, the command will be confined by the profile in the new policy namespace. If only a namespace is specified, the profile name of the current confinement will be used. If neither a profile or namespace is specified, the command will be run using standard profile attachment—as if run without aa-exec.

aa-notify

aa-notify is a handy utility that displays AppArmor notifications in your desktop environment. You can also configure it to display a summary of notifications for the specified number of recent days. For more information, see Section 24.7.3.13, “aa-notify”.

20.2 Determining Programs to Immunize

Now that you have familiarized yourself with AppArmor, start selecting the applications for which to build profiles. Programs that need profiling are those that mediate privilege. The following programs have access to resources that the person using the program does not have, so they grant the privilege to the user when used:

cron Jobs

Programs that are run periodically by cron. Such programs read input from a variety of sources and can run with special privileges, sometimes with as much as root privilege. For example, cron can run /usr/sbin/logrotate daily to rotate, compress, or even mail system logs. For instructions for finding these types of programs, refer to Section 20.3, “Immunizing cron Jobs”.

Web Applications

Programs that can be invoked through a Web browser, including CGI Perl scripts, PHP pages, and more complex Web applications. For instructions for finding these types of programs, refer to Section 20.4.1, “Immunizing Web Applications”.

Network Agents

Programs (servers and clients) that have open network ports. User clients, such as mail clients and Web browsers mediate privilege. These programs run with the privilege to write to the user's home directory and they process input from potentially hostile remote sources, such as hostile Web sites and e-mailed malicious code. For instructions for finding these types of programs, refer to Section 20.4.2, “Immunizing Network Agents”.

Conversely, unprivileged programs do not need to be profiled. For example, a shell script might invoke the cp program to copy a file. Because cp does not by default have its own profile or subprofile, it inherits the profile of the parent shell script. Thus cp can copy any files that the parent shell script's profile can read and write.

20.3 Immunizing cron Jobs

To find programs that are run by cron, inspect your local cron configuration. Unfortunately, cron configuration is rather complex, so there are numerous files to inspect. Periodic cron jobs are run from these files:

/etc/crontab 
/etc/cron.d/* 
/etc/cron.daily/* 
/etc/cron.hourly/*
/etc/cron.monthly/* 
/etc/cron.weekly/*

The crontab command lists/edits the current user's crontab. To manipulate root's cron jobs, first become root, and then edit the tasks with crontab -e or list them with crontab -l.

20.4 Immunizing Network Applications

An automated method for finding network server daemons that should be profiled is to use the aa-unconfined tool.

The aa-unconfined tool uses the command netstat -nlp to inspect open ports from inside your computer, detect the programs associated with those ports, and inspect the set of AppArmor profiles that you have loaded. aa-unconfined then reports these programs along with the AppArmor profile associated with each program, or reports none (if the program is not confined).

Note
Note

If you create a new profile, you must restart the program that has been profiled to have it be effectively confined by AppArmor.

Below is a sample aa-unconfined output:

37021 /usr/sbin/sshd2 confined
   by '/usr/sbin/sshd3 (enforce)' 
4040 /usr/sbin/ntpd confined by '/usr/sbin/ntpd (enforce)' 
4373 /usr/lib/postfix/master confined by '/usr/lib/postfix/master (enforce)' 
4505 /usr/sbin/httpd2-prefork confined by '/usr/sbin/httpd2-prefork (enforce)'
646 /usr/lib/wicked/bin/wickedd-dhcp4 not confined
647 /usr/lib/wicked/bin/wickedd-dhcp6 not confined
5592 /usr/bin/ssh not confined
7146 /usr/sbin/cupsd confined by '/usr/sbin/cupsd (complain)'

1

The first portion is a number. This number is the process ID number (PID) of the listening program.

2

The second portion is a string that represents the absolute path of the listening program

3

The final portion indicates the profile confining the program, if any.

Note
Note

aa-unconfined requires root privileges and should not be run from a shell that is confined by an AppArmor profile.

aa-unconfined does not distinguish between one network interface and another, so it reports all unconfined processes, even those that might be listening to an internal LAN interface.

Finding user network client applications is dependent on your user preferences. The aa-unconfined tool detects and reports network ports opened by client applications, but only those client applications that are running at the time the aa-unconfined analysis is performed. This is a problem because network services tend to be running all the time, while network client applications tend only to be running when the user is interested in them.

Applying AppArmor profiles to user network client applications is also dependent on user preferences. Therefore, we leave the profiling of user network client applications as an exercise for the user.

To aggressively confine desktop applications, the aa-unconfined command supports a --paranoid option, which reports all processes running and the corresponding AppArmor profiles that might or might not be associated with each process. The user can then decide whether each of these programs needs an AppArmor profile.

If you have new or modified profiles, you can submit them to the <> mailing list along with a use case for the application behavior that you exercised. The AppArmor team reviews and may submit the work into SUSE Linux Enterprise Server. We cannot guarantee that every profile will be included, but we make a sincere effort to include as much as possible.

20.4.1 Immunizing Web Applications

To find Web applications, investigate your Web server configuration. The Apache Web server is highly configurable and Web applications can be stored in many directories, depending on your local configuration. SUSE Linux Enterprise Server, by default, stores Web applications in /srv/www/cgi-bin/. To the maximum extent possible, each Web application should have an AppArmor profile.

Once you find these programs, you can use the aa-genprof and aa-logprof tools to create or update their AppArmor profiles.

Because CGI programs are executed by the Apache Web server, the profile for Apache itself, usr.sbin.httpd2-prefork for Apache2 on SUSE Linux Enterprise Server, must be modified to add execute permissions to each of these programs. For example, adding the line /srv/www/cgi-bin/my_hit_counter.pl rPx grants Apache permission to execute the Perl script my_hit_counter.pl and requires that there be a dedicated profile for my_hit_counter.pl. If my_hit_counter.pl does not have a dedicated profile associated with it, the rule should say /srv/www/cgi-bin/my_hit_counter.pl rix to cause my_hit_counter.pl to inherit the usr.sbin.httpd2-prefork profile.

Some users might find it inconvenient to specify execute permission for every CGI script that Apache might invoke. Instead, the administrator can grant controlled access to collections of CGI scripts. For example, adding the line /srv/www/cgi-bin/*.{pl,py,pyc} rix allows Apache to execute all files in /srv/www/cgi-bin/ ending in .pl (Perl scripts) and .py or .pyc (Python scripts). As above, the ix part of the rule causes Python scripts to inherit the Apache profile, which is appropriate if you do not want to write individual profiles for each CGI script.

Note
Note

If you want the subprocess confinement module (apache2-mod-apparmor) functionality when Web applications handle Apache modules (mod_perl and mod_php), use the ChangeHat features when you add a profile in YaST or at the command line. To take advantage of the subprocess confinement, refer to Section 25.2, “Managing ChangeHat-Aware Applications”.

Profiling Web applications that use mod_perl and mod_php requires slightly different handling. In this case, the program is a script interpreted directly by the module within the Apache process, so no exec happens. Instead, the AppArmor version of Apache calls change_hat() using a subprofile (a hat) corresponding to the name of the URI requested.

Note
Note

The name presented for the script to execute might not be the URI, depending on how Apache has been configured for where to look for module scripts. If you have configured your Apache to place scripts in a different place, the different names appear in the log file when AppArmor complains about access violations. See Chapter 27, Managing Profiled Applications.

For mod_perl and mod_php scripts, this is the name of the Perl script or the PHP page requested. For example, adding this subprofile allows the localtime.php page to execute and access to the local system time and locale files:

/usr/bin/httpd2-prefork {
  # ...
  ^/cgi-bin/localtime.php {
    /etc/localtime                  r,
    /srv/www/cgi-bin/localtime.php  r,
    /usr/lib/locale/**              r,
  }
}

If no subprofile has been defined, the AppArmor version of Apache applies the DEFAULT_URI hat. This subprofile is sufficient to display a Web page. The DEFAULT_URI hat that AppArmor provides by default is the following:

^DEFAULT_URI {
    /usr/sbin/suexec2                  mixr,
    /var/log/apache2/**                rwl,
    @{HOME}/public_html                r,
    @{HOME}/public_html/**             r,
    /srv/www/htdocs                    r,
    /srv/www/htdocs/**                 r,
    /srv/www/icons/*.{gif,jpg,png}     r,
    /srv/www/vhosts                    r,
    /srv/www/vhosts/**                 r,
    /usr/share/apache2/**              r,
    /var/lib/php/sess_*                rwl 
}

To use a single AppArmor profile for all Web pages and CGI scripts served by Apache, a good approach is to edit the DEFAULT_URI subprofile. For more information on confining Web applications with Apache, see Chapter 25, Profiling Your Web Applications Using ChangeHat.

20.4.2 Immunizing Network Agents

To find network server daemons and network clients (such as fetchmail or Firefox) that need to be profiled, you should inspect the open ports on your machine. Also consider the programs that are answering on those ports, and provide profiles for as many of those programs as possible. If you provide profiles for all programs with open network ports, an attacker cannot get to the file system on your machine without passing through an AppArmor profile policy.

Scan your server for open network ports manually from outside the machine using a scanner (such as nmap), or from inside the machine using the netstat --inet -n -p command as root. Then, inspect the machine to determine which programs are answering on the discovered open ports.

Tip
Tip

Refer to the man page of the netstat command for a detailed reference of all possible options.

21 Profile Components and Syntax

  • Filename: apparmor_profiles.xml
  • ID: cha.apparmor.profiles

Building AppArmor profiles to confine an application is very straightforward and intuitive. AppArmor ships with several tools that assist in profile creation. It does not require you to do any programming or script handling. The only task that is required of the administrator is to determine a policy of strictest access and execute permissions for each application that needs to be hardened.

Updates or modifications to the application profiles are only required if the software configuration or the desired range of activities changes. AppArmor offers intuitive tools to handle profile updates and modifications.

You are ready to build AppArmor profiles after you select the programs to profile. To do so, it is important to understand the components and syntax of profiles. AppArmor profiles contain several building blocks that help build simple and reusable profile code:

Include Files

Include statements are used to pull in parts of other AppArmor profiles to simplify the structure of new profiles.

Abstractions

Abstractions are include statements grouped by common application tasks.

Program Chunks

Program chunks are include statements that contain chunks of profiles that are specific to program suites.

Capability Entries

Capability entries are profile entries for any of the POSIX.1e http://en.wikipedia.org/wiki/POSIX#POSIX.1 Linux capabilities allowing a fine-grained control over what a confined process is allowed to do through system calls that require privileges.

Network Access Control Entries

Network Access Control Entries mediate network access based on the address type and family.

Local Variable Definitions

Local variables define shortcuts for paths.

File Access Control Entries

File Access Control Entries specify the set of files an application can access.

rlimit Entries

rlimit entries set and control an application's resource limits.

For help determining the programs to profile, refer to Section 20.2, “Determining Programs to Immunize”. To start building AppArmor profiles with YaST, proceed to Chapter 23, Building and Managing Profiles with YaST. To build profiles using the AppArmor command line interface, proceed to Chapter 24, Building Profiles from the Command Line.

21.1 Breaking an AppArmor Profile into Its Parts

The easiest way of explaining what a profile consists of and how to create one is to show the details of a sample profile, in this case for a hypothetical application called /usr/bin/foo:

#include <tunables/global>1

# a comment naming the application to confine
/usr/bin/foo2 {3
   #include <abstractions/base>4

   capability setgid5,
   network inet tcp6,

   link /etc/sysconfig/foo -> /etc/foo.conf,7
   /bin/mount            ux,
   /dev/{,u}8random     r,
   /etc/ld.so.cache      r,
   /etc/foo/*            r,
   /lib/ld-*.so*         mr,
   /lib/lib*.so*         mr,
   /proc/[0-9]**         r,
   /usr/lib/**           mr,
   /tmp/                 r,9
   /tmp/foo.pid          wr,
   /tmp/foo.*            lrw,
   /@{HOME}10/.foo_file   rw,
   /@{HOME}/.foo_lock    kw,
   owner11 /shared/foo/** rw,
   /usr/bin/foobar       Cx,12
   /bin/**               Px -> bin_generic,13

   # a comment about foo's local (children) profile for /usr/bin/foobar.

   profile /usr/bin/foobar14 {
      /bin/bash          rmix,
      /bin/cat           rmix,
      /bin/more          rmix,
      /var/log/foobar*   rwl,
      /etc/foobar        r,
   }

  # foo's hat, bar.
   ^bar15 {
    /lib/ld-*.so*         mr,
    /usr/bin/bar          px,
    /var/spool/*          rwl,
   }
}

1

This loads a file containing variable definitions.

2

The normalized path to the program that is confined.

3

The curly braces ({}) serve as a container for include statements, subprofiles, path entries, capability entries, and network entries.

4

This directive pulls in components of AppArmor profiles to simplify profiles.

5

Capability entry statements enable each of the 29 POSIX.1e draft capabilities.

6

A directive determining the kind of network access allowed to the application. For details, refer to Section 21.5, “Network Access Control”.

7

A link pair rule specifying the source and the target of a link. See Section 21.7.6, “Link Pair” for more information.

8

The curly braces ({}) here allow for each of the listed possibilities, one of which is the empty string.

9

A path entry specifying what areas of the file system the program can access. The first part of a path entry specifies the absolute path of a file (including regular expression globbing) and the second part indicates permissible access modes (for example r for read, w for write, and x for execute). A whitespace of any kind (spaces or tabs) can precede the path name, but must separate the path name and the mode specifier. Spaces between the access mode and the trailing comma are optional. Find a comprehensive overview of the available access modes in Section 21.7, “File Permission Access Modes”.

10

This variable expands to a value that can be changed without changing the entire profile.

11

An owner conditional rule, granting read and write permission on files owned by the user. Refer to Section 21.7.8, “Owner Conditional Rules” for more information.

12

This entry defines a transition to the local profile /usr/bin/foobar. Find a comprehensive overview of the available execute modes in Section 21.8, “Execute Modes”.

13

A named profile transition to the profile bin_generic located in the global scope. See Section 21.8.7, “Named Profile Transitions” for details.

14

The local profile /usr/bin/foobar is defined in this section.

15

This section references a hat subprofile of the application. For more details on AppArmor's ChangeHat feature, refer to Chapter 25, Profiling Your Web Applications Using ChangeHat.

When a profile is created for a program, the program can access only the files, modes, and POSIX capabilities specified in the profile. These restrictions are in addition to the native Linux access controls.

Example:  To gain the capability CAP_CHOWN, the program must have both access to CAP_CHOWN under conventional Linux access controls (typically, be a root-owned process) and have the capability chown in its profile. Similarly, to be able to write to the file /foo/bar the program must have both the correct user ID and mode bits set in the files attributes and have /foo/bar w in its profile.

Attempts to violate AppArmor rules are recorded in /var/log/audit/audit.log if the audit package is installed, or in /var/log/messages, or only in journalctl if no traditional syslog is installed. Often AppArmor rules prevent an attack from working because necessary files are not accessible and, in all cases, AppArmor confinement restricts the damage that the attacker can do to the set of files permitted by AppArmor.

21.2 Profile Types

AppArmor knows four different types of profiles: standard profiles, unattached profiles, local profiles and hats. Standard and unattached profiles are stand-alone profiles, each stored in a file under /etc/apparmor.d/. Local profiles and hats are children profiles embedded inside of a parent profile used to provide tighter or alternate confinement for a subtask of an application.

21.2.1 Standard Profiles

The default AppArmor profile is attached to a program by its name, so a profile name must match the path to the application it is to confine.

/usr/bin/foo {
...
}

This profile will be automatically used whenever an unconfined process executes /usr/bin/foo.

21.2.2 Unattached Profiles

Unattached profiles do not reside in the file system namespace and therefore are not automatically attached to an application. The name of an unattached profile is preceded by the keyword profile. You can freely choose a profile name, except for the following limitations: the name must not begin with a : or . character. If it contains a whitespace, it must be quoted. If the name begins with a /, the profile is considered to be a standard profile, so the following two profiles are identical:

profile /usr/bin/foo {
...
}
/usr/bin/foo {
...
}

Unattached profiles are never used automatically, nor can they be transitioned to through a Px rule. They need to be attached to a program by either using a named profile transition (see Section 21.8.7, “Named Profile Transitions”) or with the change_profile rule (see Section 21.2.5, “Change rules”).

Unattached profiles are useful for specialized profiles for system utilities that generally should not be confined by a system-wide profile (for example, /bin/bash). They can also be used to set up roles or to confine a user.

21.2.3 Local Profiles

Local profiles provide a convenient way to provide specialized confinement for utility programs launched by a confined application. They are specified like standard profiles, except that they are embedded in a parent profile and begin with the profile keyword:

/parent/profile {
   ...
   profile /local/profile {
      ...
   }
}

To transition to a local profile, either use a cx rule (see Section 21.8.2, “Discrete Local Profile Execute Mode (Cx)”) or a named profile transition (see Section 21.8.7, “Named Profile Transitions”).

21.2.4 Hats

AppArmor "hats" are a local profiles with some additional restrictions and an implicit rule allowing for change_hat to be used to transition to them. Refer to Chapter 25, Profiling Your Web Applications Using ChangeHat for a detailed description.

21.2.5 Change rules

AppArmor provides change_hat and change_profile rules that control domain transitioning. change_hat are specified by defining hats in a profile, while change_profile rules refer to another profile and start with the keyword change_profile:

change_profile -> /usr/bin/foobar,

Both change_hat and change_profile provide for an application directed profile transition, without having to launch a separate application. change_profile provides a generic one way transition between any of the loaded profiles. change_hat provides for a returnable parent child transition where an application can switch from the parent profile to the hat profile and if it provides the correct secret key return to the parent profile at a later time.

change_profile is best used in situations where an application goes through a trusted setup phase and then can lower its privilege level. Any resources mapped or opened during the start-up phase may still be accessible after the profile change, but the new profile will restrict the opening of new resources, and will even limit some resources opened before the switch. Specifically, memory resources will still be available while capability and file resources (as long as they are not memory mapped) can be limited.

change_hat is best used in situations where an application runs a virtual machine or an interpreter that does not provide direct access to the applications resources (for example Apache's mod_php). Since change_hat stores the return secret key in the application's memory the phase of reduced privilege should not have direct access to memory. It is also important that file access is properly separated, since the hat can restrict accesses to a file handle but does not close it. If an application does buffering and provides access to the open files with buffering, the accesses to these files might not be seen by the kernel and hence not restricted by the new profile.

Warning
Warning: Safety of Domain Transitions

The change_hat and change_profile domain transitions are less secure than a domain transition done through an exec because they do not affect a process's memory mappings, nor do they close resources that have already been opened.

21.3 Include Statements

Include statements are directives that pull in components of other AppArmor profiles to simplify profiles. Include files retrieve access permissions for programs. By using an include, you can give the program access to directory paths or files that are also required by other programs. Using includes can reduce the size of a profile.

Include statements normally begin with a hash (#) sign. This is confusing because the same hash sign is used for comments inside profile files. Because of this, #include is treated as an include only if there is no preceding # (##include is a comment) and there is no whitespace between # and include (# include is a comment).

You can also use include without the leading #.

include "/etc/apparmor.d/abstractions/foo"

is the same as using

#include "/etc/apparmor.d/abstractions/foo"
Note
Note: No Trailing ','

Note that because includes follow the C pre-processor syntax, they do not have a trailing ',' like most AppArmor rules.

By slight changes in syntax, you can modify the behavior of include. If you use "" around the including path, you instruct the parser to do an absolute or relative path lookup.

include "/etc/apparmor.d/abstractions/foo"   # absolute path
include "abstractions/foo"   # relative path to the directory of current file

Note that when using relative path includes, when the file is included, it is considered the new current file for its includes. For example, suppose you are in the /etc/apparmor.d/bar file, then

include "abstractions/foo"

includes the file /etc/apparmor.d/abstractions/foo. If then there is

include "example"

inside the /etc/apparmor.d/abstractions/foo file, it includes /etc/apparmor.d/abstractions/example.

The use of <> specifies to try the include path (specified by -I, defaults to the /etc/apparmor.d directory) in an ordered way. So assuming the include path is

-I /etc/apparmor.d/ -I /usr/share/apparmor/

then the include statement

include <abstractions/foo>

will try /etc/apparmor.d/abstractions/foo, and if that file does not exist, the next try is /usr/share/apparmor/abstractions/foo.

Tip
Tip

The default include path can be overridden manually by passing -I to the apparmor_parser, or by setting the include paths in /etc/apparmor/parser.conf:

Include /usr/share/apparmor/
Include /etc/apparmor.d/

Multiple entries are allowed, and they are taken in the same order as when they are when using -I or --Include from the apparmor_parser command line.

If an include ends with '/', this is considered a directory include, and all files within the directory are included.

To assist you in profiling your applications, AppArmor provides three classes of includes: abstractions, program chunks and tunables.

21.3.1 Abstractions

Abstractions are includes that are grouped by common application tasks. These tasks include access to authentication mechanisms, access to name service routines, common graphics requirements, and system accounting. Files listed in these abstractions are specific to the named task. Programs that require one of these files usually also require other files listed in the abstraction file (depending on the local configuration and the specific requirements of the program). Find abstractions in /etc/apparmor.d/abstractions.

21.3.2 Program Chunks

The program-chunks directory (/etc/apparmor.d/program-chunks) contains some chunks of profiles that are specific to program suites and not generally useful outside of the suite, thus are never suggested for use in profiles by the profile wizards (aa-logprof and aa-genprof). Currently, program chunks are only available for the postfix program suite.

21.3.3 Tunables

The tunables directory (/etc/apparmor.d/tunables) contains global variable definitions. When used in a profile, these variables expand to a value that can be changed without changing the entire profile. Add all the tunables definitions that should be available to every profile to /etc/apparmor.d/tunables/global.

21.4 Capability Entries (POSIX.1e)

Capability rules are simply the word capability followed by the name of the POSIX.1e capability as defined in the capabilities(7) man page. You can list multiple capabilities in a single rule, or grant all implemented capabilities with the bare keyword capability.

capability dac_override sys_admin,   # multiple capabilities
capability,                          # grant all capabilities

21.5 Network Access Control

AppArmor allows mediation of network access based on the address type and family. The following illustrates the network access rule syntax:

network [[<domain>1][<type2>][<protocol3>]]

1

Supported domains: inet, ax25, ipx, appletalk, netrom, bridge, x25, inet6, rose, netbeui, security, key, packet, ash, econet, atmsvc, sna, irda, pppox, wanpipe, bluetooth, unix, atmpvc,netlink, llc, can, tipc, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock

2

Supported types: stream, dgram, seqpacket, rdm, raw, packet

3

Supported protocols: tcp, udp, icmp

The AppArmor tools support only family and type specification. The AppArmor module emits only network DOMAIN TYPE in ACCESS DENIED messages. And only these are output by the profile generation tools, both YaST and command line.

The following examples illustrate possible network-related rules to be used in AppArmor profiles. Note that the syntax of the last two are not currently supported by the AppArmor tools.

network1,
network inet2,
network inet63,
network inet stream4,
network inet tcp5,
network tcp6,

1

Allow all networking. No restrictions applied with regard to domain, type, or protocol.

2

Allow general use of IPv4 networking.

3

Allow general use of IPv6 networking.

4

Allow the use of IPv4 TCP networking.

5

Allow the use of IPv4 TCP networking, paraphrasing the rule above.

6

Allow the use of both IPv4 and IPv6 TCP networking.

21.6 Profile Names, Flags, Paths, and Globbing

A profile is usually attached to a program by specifying a full path to the program's executable. For example in the case of a standard profile (see Section 21.2.1, “Standard Profiles”), the profile is defined by

/usr/bin/foo { ... }

The following sections describe several useful techniques that can be applied when naming a profile or putting a profile in the context of other existing ones, or specifying file paths.

AppArmor explicitly distinguishes directory path names from file path names. Use a trailing / for any directory path that needs to be explicitly distinguished:

/some/random/example/* r

Allow read access to files in the /some/random/example directory.

/some/random/example/ r

Allow read access to the directory only.

/some/**/ r

Give read access to any directories below /some (but not /some/ itself).

/some/random/example/** r

Give read access to files and directories under /some/random/example (but not /some/random/example/ itself).

/some/random/example/**[^/] r

Give read access to files under /some/random/example. Explicitly exclude directories ([^/]).

Globbing (or regular expression matching) is when you modify the directory path using wild cards to include a group of files or subdirectories. File resources can be specified with a globbing syntax similar to that used by popular shells, such as csh, Bash, and zsh.

*

Substitutes for any number of any characters, except /.

Example: An arbitrary number of file path elements.

**

Substitutes for any number of characters, including /.

Example: An arbitrary number of path elements, including entire directories.

?

Substitutes for any single character, except /.

[abc]

Substitutes for the single character a, b, or c.

Example: a rule that matches /home[01]/*/.plan allows a program to access .plan files for users in both /home0 and /home1.

[a-c]

Substitutes for the single character a, b, or c.

{ab,cd}

Expands to one rule to match ab and one rule to match cd.

Example: a rule that matches /{usr,www}/pages/** grants access to Web pages in both /usr/pages and /www/pages.

[^a]

Substitutes for any character except a.

21.6.1 Profile Flags

Profile flags control the behavior of the related profile. You can add profile flags to the profile definition by editing it manually, see the following syntax:

/path/to/profiled/binary flags=(list_of_flags) {
  [...]
}

You can use multiple flags separated by a comma ',' or space ' '. There are three basic types of profile flags: mode, relative, and attach flags.

Mode flag is complain (illegal accesses are allowed and logged). If it is omitted, the profile is in enforce mode (enforces the policy).

Tip
Tip

A more flexible way of setting the whole profile into complain mode is to create a symbolic link from the profile file inside the /etc/apparmor.d/force-complain/ directory.

ln -s /etc/apparmor.d/bin.ping /etc/apparmor.d/force-complain/bin.ping

Relative flags are chroot_relative (states that the profile is relative to the chroot instead of namespace) or namespace_relative (the default, with the path being relative to outside the chroot). They are mutually exclusive.

Attach flags consist of two pairs of mutually exclusive flags: attach_disconnected or no_attach_disconnected (determine if path names resolved to be outside of the namespace are attached to the root, which means they have the '/' character at the beginning), and chroot_attach or chroot_no_attach (control path name generation when in a chroot environment while a file is accessed that is external to the chroot but within the namespace).

21.6.2 Using Variables in Profiles

AppArmor allows to use variables holding paths in profiles. Use global variables to make your profiles portable and local variables to create shortcuts for paths.

A typical example of when global variables come in handy are network scenarios in which user home directories are mounted in different locations. Instead of rewriting paths to home directories in all affected profiles, you only need to change the value of a variable. Global variables are defined under /etc/apparmor.d/tunables and need to be made available via an include statement. Find the variable definitions for this use case (@{HOME} and @{HOMEDIRS}) in the /etc/apparmor.d/tunables/home file.

Local variables are defined at the head of a profile. This is useful to provide the base of for a chrooted path, for example:

@{CHROOT_BASE}=/tmp/foo
/sbin/rsyslogd {
...
# chrooted applications
@{CHROOT_BASE}/var/lib/*/dev/log w,
@{CHROOT_BASE}/var/log/** w,
...
}

In the following example, while @{HOMEDIRS} lists where all the user home directories are stored, @{HOME} is a space-separated list of home directories. Later on, @{HOMEDIRS} is expanded by two new specific places where user home directories are stored.

@{HOMEDIRS}=/home/
@{HOME}=@{HOMEDIRS}/*/ /root/
[...]
@{HOMEDIRS}+=/srv/nfs/home/ /mnt/home/
Note
Note

With the current AppArmor tools, variables can only be used when manually editing and maintaining a profile.

21.6.3 Pattern Matching

Profile names can contain globbing expressions allowing the profile to match against multiple binaries.

The following example is valid for systems where the foo binary resides either in /usr/bin or /bin.

/{usr/,}bin/foo { ... }

In the following example, when matching against the executable /bin/foo, the /bin/foo profile is an exact match so it is chosen. For the executable /bin/fat, the profile /bin/foo does not match, and because the /bin/f* profile is more specific (less general) than /bin/**, the /bin/f* profile is chosen.

/bin/foo { ... }

/bin/f*  { ... }

/bin/**  { ... }

For more information on profile name globbing examples, see the man page of AppArmor, man 5 apparmor.d,, section Globbing.

21.6.4 Namespaces

Namespaces are used to provide different profiles sets. Say one for the system, another for a chroot environment or container. Namespaces are hierarchical—a namespace can see its children but a child cannot see its parent. Namespace names start with a colon : followed by an alphanumeric string, a trailing colon : and an optional double slash //, such as

:childNameSpace://

Profiles loaded to a child namespace will be prefixed with their namespace name (viewed from a parent's perspective):

:childNameSpace://apache

Namespaces can be entered via the change_profile API, or named profile transitions:

/path/to/executable px -> :childNameSpace://apache

21.6.5 Profile Naming and Attachment Specification

Profiles can have a name, and an attachment specification. This allows for profiles with a logical name that can be more meaningful to users/administrators than a profile name that contains pattern matching (see Section 21.6.3, “Pattern Matching”). For example, the default profile

/** { ... }

can be named

profile default /** { ... }

Also, a profile with pattern matching can be named. For example:

/usr/lib/firefox-3.*/firefox-*bin { ... }

can be named

profile firefox /usr/lib/firefox-3.*/firefox-*bin { ... }

21.6.6 Alias Rules

Alias rules provide an alternative way to manipulate profile path mappings to site specific layouts. They are an alternative form of path rewriting to using variables, and are done post variable resolution. The alias rule says to treat rules that have the same source prefix as if the rules are at target prefix.

alias /home/ -> /usr/home/

All the rules that have a prefix match to /home/ will provide access to /usr/home/. For example

/home/username/** r,

allows as well access to

/usr/home/username/** r,

Aliases provide a quick way of remapping rules without the need to rewrite them. They keep the source path still accessible—in our example, the alias rule keeps the paths under /home/ still accessible.

With the alias rule, you can point to multiple targets at the same time.

alias /home/ -> /usr/home/
alias /home/ -> /mnt/home/
Note
Note

With the current AppArmor tools, alias rules can only be used when manually editing and maintaining a profile.

Tip
Tip

Insert global alias definitions in the file /etc/apparmor.d/tunables/alias.

21.7 File Permission Access Modes

File permission access modes consist of combinations of the following modes:

r

Read mode

w

Write mode (mutually exclusive to a)

a

Append mode (mutually exclusive to w)

k

File locking mode

l

Link mode

link FILE -> TARGET

Link pair rule (cannot be combined with other access modes)

21.7.1 Read Mode (r)

Allows the program to have read access to the resource. Read access is required for shell scripts and other interpreted content and determines if an executing process can core dump.

21.7.2 Write Mode (w)

Allows the program to have write access to the resource. Files must have this permission if they are to be unlinked (removed).

21.7.3 Append Mode (a)

Allows a program to write to the end of a file. In contrast to the w mode, the append mode does not include the ability to overwrite data, to rename, or to remove a file. The append permission is typically used with applications who need to be able to write to log files, but which should not be able to manipulate any existing data in the log files. As the append permission is a subset of the permissions associated with the write mode, the w and a permission flags cannot be used together and are mutually exclusive.

21.7.4 File Locking Mode (k)

The application can take file locks. Former versions of AppArmor allowed files to be locked if an application had access to them. By using a separate file locking mode, AppArmor makes sure locking is restricted only to those files which need file locking and tightens security as locking can be used in several denial of service attack scenarios.

21.7.7 Optional allow and file Rules

The allow prefix is optional, and it is idiomatically implied if not specified and the deny (see Section 21.7.9, “Deny Rules”) keyword is not used.

allow file /example r,
allow /example r,
allow network,

You can also use the optional file keyword. If you omit it and there are no other rule types that start with a keyword, such as network or mount, it is automatically implied.

file /example/rule r,

is equivalent to

/example/rule r,

The following rule grants access to all files:

file,

which is equal to

/** rwmlk,

File rules can use leading or trailing permissions. The permissions should not be specified as a trailing permission, but rather used at the start of the rule. This is important in that it makes file rules behave like any other rule types.

/path rw,            # old style
rw /path,            # leading permission
file rw /path,       # with explicit 'file' keyword
allow file rw /path, # optional 'allow' keyword added

21.7.8 Owner Conditional Rules

The file rules can be extended so that they can be conditional upon the user being the owner of the file (the fsuid needs to match the file's uid). For this purpose the owner keyword is put in front of the rule. Owner conditional rules accumulate like regular file rules do.

owner /home/*/** rw

When using file ownership conditions with link rules the ownership test is done against the target file so the user must own the file to be able to link to it.

Note
Note: Precedence of Regular File Rules

Owner conditional rules are considered a subset of regular file rules. If a regular file rule overlaps with an owner conditional file rule, the rules are merged. Consider the following example.

/foo r,
owner /foo rw,  # or w,

The rules are merged—it results in r for everybody, and w for the owner only.

Tip
Tip

To address everybody but the owner of the file, use the keyword other.

owner /foo rw,
other /foo r,

21.7.9 Deny Rules

Deny rules can be used to annotate or quiet known rejects. The profile generating tools will not ask about a known reject treated with a deny rule. Such a reject will also not show up in the audit logs when denied, keeping the log files lean. If this is not desired, put the keyword audit in front of the deny entry.

It is also possible to use deny rules in combination with allow rules. This allows you to specify a broad allow rule, and then subtract a few known files that should not be allowed. Deny rules can also be combined with owner rules, to deny files owned by the user. The following example allows read/write access to everything in a users directory except write access to the .ssh/ files:

deny /home/*/.ssh/** w,
owner /home/*/** rw,

The extensive use of deny rules is generally not encouraged, because it makes it much harder to understand what a profile does. However a judicious use of deny rules can simplify profiles. Therefore the tools only generate profiles denying specific files and will not use globbing in deny rules. Manually edit your profiles to add deny rules using globbing. Updating such profiles using the tools is safe, because the deny entries will not be touched.

21.8 Execute Modes

Execute modes, also named profile transitions, consist of the following modes:

Px

Discrete profile execute mode

Cx

Discrete local profile execute mode

Ux

Unconfined execute mode

ix

Inherit execute mode

m

Allow PROT_EXEC with mmap(2) calls

21.8.1 Discrete Profile Execute Mode (Px)

This mode requires that a discrete security profile is defined for a resource executed at an AppArmor domain transition. If there is no profile defined, the access is denied.

Incompatible with Ux, ux, px, and ix.

21.8.2 Discrete Local Profile Execute Mode (Cx)

As Px, but instead of searching the global profile set, Cx only searches the local profiles of the current profile. This profile transition provides a way for an application to have alternate profiles for helper applications.

Note
Note: Limitations of the Discrete Local Profile Execute Mode (Cx)

Currently, Cx transitions are limited to top level profiles and cannot be used in hats and children profiles. This restriction will be removed in the future.

Incompatible with Ux, ux, Px, px, cx, and ix.

21.8.3 Unconfined Execute Mode (Ux)

Allows the program to execute the resource without any AppArmor profile applied to the executed resource. This mode is useful when a confined program needs to be able to perform a privileged operation, such as rebooting the machine. By placing the privileged section in another executable and granting unconfined execution rights, it is possible to bypass the mandatory constraints imposed on all confined processes. Allowing a root process to go unconfined means it can change AppArmor policy itself. For more information about what is constrained, see the apparmor(7) man page.

This mode is incompatible with ux, px, Px, and ix.

21.8.4 Unsafe Exec Modes

Use the lowercase versions of exec modes—px, cx, ux—only in very special cases. They do not scrub the environment of variables such as LD_PRELOAD. As a result, the calling domain may have an undue amount of influence over the called resource. Use these modes only if the child absolutely must be run unconfined and LD_PRELOAD must be used. Any profile using such modes provides negligible security. Use at your own risk.

21.8.5 Inherit Execute Mode (ix)

ix prevents the normal AppArmor domain transition on execve(2) when the profiled program executes the named program. Instead, the executed resource inherits the current profile.

This mode is useful when a confined program needs to call another confined program without gaining the permissions of the target's profile or losing the permissions of the current profile. There is no version to scrub the environment because ix executions do not change privileges.

Incompatible with cx, ux, and px. Implies m.

21.8.6 Allow Executable Mapping (m)

This mode allows a file to be mapped into memory using mmap(2)'s PROT_EXEC flag. This flag marks the pages executable. It is used on some architectures to provide non executable data pages, which can complicate exploit attempts. AppArmor uses this mode to limit which files a well-behaved program (or all programs on architectures that enforce non executable memory access controls) may use as libraries, to limit the effect of invalid -L flags given to ld(1) and LD_PRELOAD, LD_LIBRARY_PATH, given to ld.so(8).

21.8.7 Named Profile Transitions

By default, the px and cx (and their clean exec variants, too) transition to a profile whose name matches the executable name. With named profile transitions, you can specify a profile to be transitioned to. This is useful if multiple binaries need to share a single profile, or if they need to use a different profile than their name would specify. Named profile transitions can be used with cx, Cx, px and Px. Currently there is a limit of twelve named profile transitions per profile.

Named profile transitions use -> to indicate the name of the profile that needs to be transitioned to:

/usr/bin/foo
{
  /bin/** px -> shared_profile,
  ...
  /usr/*bash cx -> local_profile,
  ...
  profile local_profile
  {
    ...
  }
}
Note
Note: Difference Between Normal and Named Transitions

When used with globbing, normal transitions provide a one to many relationship—/bin/** px will transition to /bin/ping, /bin/cat, etc, depending on the program being run.

Named transitions provide a many to one relationship—all programs that match the rule regardless of their name will transition to the specified profile.

Named profile transitions show up in the log as having the mode Nx. The name of the profile to be changed to is listed in the name2 field.

21.8.8 Fallback Modes for Profile Transitions

The px and cx transitions specify a hard dependency—if the specified profile does not exist, the exec will fail. With the inheritance fallback, the execution will succeed but inherit the current profile. To specify inheritance fallback, ix is combined with cx, Cx, px and Px into the modes cix, Cix, pix and Pix.

/path Cix -> profile_name,

or

Cix /path -> profile_name,

where -> profile_name is optional.

The same applies if you add the unconfined ux mode, where the resulting modes are cux, CUx, pux and PUx. These modes allow falling back to unconfined when the specified profile is not found.

/path PUx -> profile_name,

or

PUx /path -> profile_name,

where -> profile_name is optional.

The fallback modes can be used with named profile transitions, too.

21.8.9 Variable Settings in Execution Modes

When choosing one of the Px, Cx or Ux execution modes, take into account that the following environment variables are removed from the environment before the child process inherits it. As a consequence, applications or processes relying on any of these variables do not work anymore if the profile applied to them carries Px, Cx or Ux flags:

  • GCONV_PATH

  • GETCONF_DIR

  • HOSTALIASES

  • LD_AUDIT

  • LD_DEBUG

  • LD_DEBUG_OUTPUT

  • LD_DYNAMIC_WEAK

  • LD_LIBRARY_PATH

  • LD_ORIGIN_PATH

  • LD_PRELOAD

  • LD_PROFILE

  • LD_SHOW_AUXV

  • LD_USE_LOAD_BIAS

  • LOCALDOMAIN

  • LOCPATH

  • MALLOC_TRACE

  • NLSPATH

  • RESOLV_HOST_CONF

  • RES_OPTIONS

  • TMPDIR

  • TZDIR

21.8.10 safe and unsafe Keywords

You can use the safe and unsafe keywords for rules instead of using the case modifier of execution modes. For example

/example_rule Px,

is the same as any of the following

safe /example_rule px,
safe /example_rule Px,
safe px /example_rule,
safe Px /example_rule,

and the rule

/example_rule px,

is the same as any of

unsafe /example_rule px,
unsafe /example_rule Px,
unsafe px /example_rule,
unsafe Px /example_rule,

The safe/unsafe keywords are mutually exclusive and can be used in a file rule after the owner keyword, so the order of rule keywords is

[audit] [deny] [owner] [safe|unsafe] file_rule

21.9 Resource Limit Control

AppArmor can set and control an application's resource limits (rlimits, also known as ulimits). By default, AppArmor does not control application's rlimits, and it will only control those limits specified in the confining profile. For more information about resource limits, refer to the setrlimit(2), ulimit(1), or ulimit(3) man pages.

AppArmor leverages the system's rlimits and as such does not provide an additional auditing that would normally occur. It also cannot raise rlimits set by the system, AppArmor rlimits can only reduce an application's current resource limits.

The values will be inherited by the children of a process and will remain even if a new profile is transitioned to or the application becomes unconfined. So when an application transitions to a new profile, that profile can further reduce the application's rlimits.

AppArmor's rlimit rules will also provide mediation of setting an application's hard limits, should it try to raise them. The application cannot raise its hard limits any further than specified in the profile. The mediation of raising hard limits is not inherited as the set value is, so that when the application transitions to a new profile it is free to raise its limits as specified in the profile.

AppArmor's rlimit control does not affect an application's soft limits beyond ensuring that they are less than or equal to the application's hard limits.

AppArmor's hard limit rules have the general form of:

set rlimit RESOURCE <= value,

where RESOURCE and VALUE are to be replaced with the following values:

cpu

CPU time limit in seconds.

fsize, data, stack, core, rss, as, memlock, msgqueue

a number in bytes, or a number with a suffix where the suffix can be K/KB (kilobytes), M/MB (megabytes), G/GB (gigabytes), for example

rlimit data <= 100M,
fsize, nofile, locks, sigpending, nproc*, rtprio

a number greater or equal to 0

nice

a value between -20 and 19

*The nproc rlimit is handled different than all the other rlimits. Instead of indicating the standard process rlimit it controls the maximum number of processes that can be running under the profile at any time. When the limit is exceeded the creation of new processes under the profile will fail until the number of currently running processes is reduced.

Note
Note

Currently the tools cannot be used to add rlimit rules to profiles. The only way to add rlimit controls to a profile is to manually edit the profile with a text editor. The tools will still work with profiles containing rlimit rules and will not remove them, so it is safe to use the tools to update profiles containing them.

21.10 Auditing Rules

AppArmor provides the ability to audit given rules so that when they are matched an audit message will appear in the audit log. To enable audit messages for a given rule, the audit keyword is put in front of the rule:

audit /etc/foo/*        rw,

If it is desirable to audit only a given permission the rule can be split into two rules. The following example will result in audit messages when files are opened for writing, but not when they are opened for reading:

audit /etc/foo/*  w,
/etc/foo/*        r,
Note
Note

Audit messages are not generated for every read or write of a file but only when a file is opened for reading or writing.

Audit control can be combined with owner/other conditional file rules to provide auditing when users access files they own/do not own:

audit owner /home/*/.ssh/**       rw,
audit other /home/*/.ssh/**       r,

22 AppArmor Profile Repositories

  • Filename: apparmor_repositories.xml
  • ID: cha.apparmor.repos

AppArmor ships with a set of profiles enabled by default. These are created by the AppArmor developers, and are stored in /etc/apparmor.d. In addition to these profiles, SUSE Linux Enterprise Server ships profiles for individual applications together with the relevant application. These profiles are not enabled by default, and reside under another directory than the standard AppArmor profiles, /etc/apparmor/profiles/extras.

The AppArmor tools (YaST, aa-genprof and aa-logprof) support the use of a local repository. Whenever you start to create a new profile from scratch, and there already is an inactive profile in your local repository, you are asked whether you want to use the existing inactive one from /etc/apparmor/profiles/extras and whether you want to base your efforts on it. If you decide to use this profile, it gets copied over to the directory of profiles enabled by default (/etc/apparmor.d) and loaded whenever AppArmor is started. Any further adjustments will be done to the active profile under /etc/apparmor.d.

23 Building and Managing Profiles with YaST

  • Filename: apparmor_profiles_yast.xml
  • ID: cha.apparmor.yast

YaST provides a basic way to build profiles and manage AppArmor® profiles. It provides two interfaces: a graphical one and a text-based one. The text-based interface consumes less resources and bandwidth, making it a better choice for remote administration, or for times when a local graphical environment is inconvenient. Although the interfaces have differing appearances, they offer the same functionality in similar ways. Another alternative is to use AppArmor commands, which can control AppArmor from a terminal window or through remote connections. The command line tools are described in Chapter 24, Building Profiles from the Command Line.

Start YaST from the main menu and enter your root password when prompted for it. Alternatively, start YaST by opening a terminal window, logging in as root, and entering yast2 for the graphical mode or yast for the text-based mode.

In the Security and Users section, there is an AppArmor Configuration icon. Click it to launch the AppArmor YaST module.

23.1 Manually Adding a Profile

AppArmor enables you to create an AppArmor profile by manually adding entries into the profile. Select the application for which to create a profile, then add entries.

  1. Start YaST, select AppArmor Configuration, and click Manually Add Profile in the main window.

  2. Browse your system to find the application for which to create a profile.

  3. When you find the application, select it and click Open. A basic, empty profile appears in the AppArmor Profile Dialog window.

  4. In AppArmor Profile Dialog, add, edit, or delete AppArmor profile entries by clicking the corresponding buttons and referring to Section 23.2.1, “Adding an Entry”, Section 23.2.2, “Editing an Entry”, or Section 23.2.3, “Deleting an Entry”.

  5. When finished, click Done.

23.2 Editing Profiles

Tip
Tip

YaST offers basic manipulation for AppArmor profiles, such as creating or editing. However, the most straightforward way to edit an AppArmor profile is to use a text editor such as vi:

root # vi /etc/apparmor.d/usr.sbin.httpd2-prefork
Tip
Tip

The vi editor also includes syntax (error) highlighting and syntax error highlighting, which visually warns you when the syntax of the edited AppArmor profile is wrong.

AppArmor enables you to edit AppArmor profiles manually by adding, editing, or deleting entries. To edit a profile, proceed as follows:

  1. Start YaST, select AppArmor Configuration, and click Manage Existing Profiles in the main window.

    Choose the profile to edit
  2. From the list of profiled applications, select the profile to edit.

  3. Click Edit. The AppArmor Profile Dialog window displays the profile.

    AppArmor profile dialog
  4. In the AppArmor Profile Dialog window, add, edit, or delete AppArmor profile entries by clicking the corresponding buttons and referring to Section 23.2.1, “Adding an Entry”, Section 23.2.2, “Editing an Entry”, or Section 23.2.3, “Deleting an Entry”.

  5. When you are finished, click Done.

  6. In the pop-up that appears, click Yes to confirm your changes to the profile and reload the AppArmor profile set.

Tip
Tip: Syntax Checking in AppArmor

AppArmor contains a syntax check that notifies you of any syntax errors in profiles you are trying to process with the YaST AppArmor tools. If an error occurs, edit the profile manually as root and reload the profile set with systemctl reload apparmor.

23.2.1 Adding an Entry

The Add Entry button in the AppArmor Profile Window lists types of entries you can add to the AppArmor profile.

From the list, select one of the following:

File

In the pop-up window, specify the absolute path of a file, including the type of access permitted. When finished, click OK.

You can use globbing if necessary. For globbing information, refer to Section 21.6, “Profile Names, Flags, Paths, and Globbing”. For file access permission information, refer to Section 21.7, “File Permission Access Modes”.

Select a file to add
Directory

In the pop-up window, specify the absolute path of a directory, including the type of access permitted. You can use globbing if necessary. When finished, click OK.

For globbing information, refer to Section 21.6, “Profile Names, Flags, Paths, and Globbing”. For file access permission information, refer to Section 21.7, “File Permission Access Modes”.

Select a directory to add
Network Rule

In the pop-up window, select the appropriate network family and the socket type. For more information, refer to Section 21.5, “Network Access Control”.

Select capabilities
Capability

In the pop-up window, select the appropriate capabilities. These are statements that enable each of the 32 POSIX.1e capabilities. Refer to Section 21.4, “Capability Entries (POSIX.1e)” for more information about capabilities. When finished making your selections, click OK.

Select capabilities
Include File

In the pop-up window, browse to the files to use as includes. Includes are directives that pull in components of other AppArmor profiles to simplify profiles. For more information, refer to Section 21.3, “Include Statements”.

Hat

In the pop-up window, specify the name of the subprofile (hat) to add to your current profile and click Create Hat. For more information, refer to Chapter 25, Profiling Your Web Applications Using ChangeHat.

23.2.2 Editing an Entry

When you select Edit Entry, a pop-up window opens. From here, edit the selected entry.

In the pop-up window, edit the entry you need to modify. You can use globbing if necessary. When finished, click OK.

For globbing information, refer to Section 21.6, “Profile Names, Flags, Paths, and Globbing”. For access permission information, refer to Section 21.7, “File Permission Access Modes”.

23.2.3 Deleting an Entry

To delete an entry in a given profile, select Delete Entry. AppArmor removes the selected profile entry.

23.3 Deleting a Profile

AppArmor enables you to delete an AppArmor profile manually. Simply select the application for which to delete a profile then delete it as follows:

  1. Start YaST, select AppArmor Configuration, and click Manage Existing Profiles in the main window.

  2. Select the profile to delete.

  3. Click Delete.

  4. In the pop-up that opens, click Yes to delete the profile and reload the AppArmor profile set.

23.4 Managing AppArmor

You can change the status of AppArmor by enabling or disabling it. Enabling AppArmor protects your system from potential program exploitation. Disabling AppArmor, even if your profiles have been set up, removes protection from your system. To change the status of AppArmor, start YaST, select AppArmor Configuration, and click Settings in the main window.

The AppArmor control panel

To change the status of AppArmor, continue as described in Section 23.4.1, “Changing AppArmor Status”. To change the mode of individual profiles, continue as described in Section 23.4.2, “Changing the Mode of Individual Profiles”.

23.4.1 Changing AppArmor Status

When you change the status of AppArmor, set it to enabled or disabled. When AppArmor is enabled, it is installed, running, and enforcing the AppArmor security policies.

  1. Start YaST, select AppArmor Configuration, and click Settings in the main window.

  2. Enable AppArmor by checking Enable AppArmor or disable AppArmor by deselecting it.

  3. Click Done in the AppArmor Configuration window.

Tip
Tip

You always need to restart running programs to apply the profiles to them.

23.4.2 Changing the Mode of Individual Profiles

AppArmor can apply profiles in two different modes. In complain mode, violations of AppArmor profile rules, such as the profiled program accessing files not permitted by the profile, are detected. The violations are permitted, but also logged. This mode is convenient for developing profiles and is used by the AppArmor tools for generating profiles. Loading a profile in enforce mode enforces the policy defined in the profile, and reports policy violation attempts to rsyslogd (or auditd or journalctl, depending on system configuration).

The Profile Mode Configuration dialog allows you to view and edit the mode of currently loaded AppArmor profiles. This feature is useful for determining the status of your system during profile development. During systemic profiling (see Section 24.7.2, “Systemic Profiling”), you can use this tool to adjust and monitor the scope of the profiles for which you are learning behavior.

To edit an application's profile mode, proceed as follows:

  1. Start YaST, select AppArmor Configuration, and click Settings in the main window.

  2. In the Configure Profile Modes section, select Configure.

  3. Select the profile for which to change the mode.

  4. Select Toggle Mode to set this profile to complain mode or to enforce mode.

  5. Apply your settings and leave YaST with Done.

To change the mode of all profiles, use Set All to Enforce or Set All to Complain.

Tip
Tip: Listing the Profiles Available

By default, only active profiles are listed (any profile that has a matching application installed on your system). To set up a profile before installing the respective application, click Show All Profiles and select the profile to configure from the list that appears.

24 Building Profiles from the Command Line

  • Filename: apparmor_profiles_man.xml
  • ID: cha.apparmor.commandline

AppArmor® provides the user the ability to use a command line interface rather than a graphical interface to manage and configure the system security. Track the status of AppArmor and create, delete, or modify AppArmor profiles using the AppArmor command line tools.

Tip
Tip: Background Information

Before starting to manage your profiles using the AppArmor command line tools, check out the general introduction to AppArmor given in Chapter 20, Immunizing Programs and Chapter 21, Profile Components and Syntax.

24.1 Checking the AppArmor Status

AppArmor can be in any one of three states:

Unloaded

AppArmor is not activated in the kernel.

Running

AppArmor is activated in the kernel and is enforcing AppArmor program policies.

Stopped

AppArmor is activated in the kernel, but no policies are enforced.

Detect the state of AppArmor by inspecting /sys/kernel/security/apparmor/profiles. If cat /sys/kernel/security/apparmor/profiles reports a list of profiles, AppArmor is running. If it is empty and returns nothing, AppArmor is stopped. If the file does not exist, AppArmor is unloaded.

Manage AppArmor with systemctl. It lets you perform the following operations:

sudo systemctl start apparmor

Behavior depends on the state of AppArmor. If it is not activated, start activates and starts it, putting it in the running state. If it is stopped, start causes the re-scan of AppArmor profiles usually found in /etc/apparmor.d and puts AppArmor in the running state. If AppArmor is already running, start reports a warning and takes no action.

Note
Note: Already Running Processes

Already running processes need to be restarted to apply the AppArmor profiles on them.

sudo systemctl stop apparmor

Stops AppArmor if it is running by removing all profiles from kernel memory, effectively disabling all access controls, and putting AppArmor into the stopped state. If the AppArmor is already stopped, stop tries to unload the profiles again, but nothing happens.

sudo systemctl reload apparmor

Causes the AppArmor module to re-scan the profiles in /etc/apparmor.d without unconfining running processes. Freshly created profiles are enforced and recently deleted ones are removed from the /etc/apparmor.d directory.

24.2 Building AppArmor Profiles

The AppArmor module profile definitions are stored in the /etc/apparmor.d directory as plain text files. For a detailed description of the syntax of these files, refer to Chapter 21, Profile Components and Syntax.

All files in the /etc/apparmor.d directory are interpreted as profiles and are loaded as such. Renaming files in that directory is not an effective way of preventing profiles from being loaded. You must remove profiles from this directory to prevent them from being read and evaluated effectively, or call aa-disable on the profile, which will create a symbolic link in /etc/apparmor.d/disabled/.

You can use a text editor, such as vi, to access and make changes to these profiles. The following sections contain detailed steps for building profiles:

Adding or Creating AppArmor Profiles

Refer to Section 24.3, “Adding or Creating an AppArmor Profile”

Editing AppArmor Profiles

Refer to Section 24.4, “Editing an AppArmor Profile”

Deleting AppArmor Profiles

Refer to Section 24.6, “Deleting an AppArmor Profile”

24.3 Adding or Creating an AppArmor Profile

To add or create an AppArmor profile for an application, you can use a systemic or stand-alone profiling method, depending on your needs. Learn more about these two approaches in Section 24.7, “Two Methods of Profiling”.

24.4 Editing an AppArmor Profile

The following steps describe the procedure for editing an AppArmor profile:

  1. If you are not currently logged in as root, enter su in a terminal window.

  2. Enter the root password when prompted.

  3. Go to the profile directory with cd /etc/apparmor.d/.

  4. Enter ls to view all profiles currently installed.

  5. Open the profile to edit in a text editor, such as vim.

  6. Make the necessary changes, then save the profile.

  7. Restart AppArmor by entering systemctl reload apparmor in a terminal window.

24.5 Unloading Unknown AppArmor Profiles

Warning
Warning: Danger of Unloading Wanted Profiles

aa-remove-unkown will unload all profiles that are not stored in /etc/apparmor.d, for example automatically generated LXD profiles. This may compromise the security of the system. Use the -n parameter to list all profiles that will be unloaded.

To unload all profiles that are not longer in /etc/apparmor.d/ AppArmor profiles, run:

tux > sudo aa-remove-unknown

You can print a list of profiles that will be removed:

tux > sudo aa-remove-unknown -n

24.6 Deleting an AppArmor Profile

The following steps describe the procedure for deleting an AppArmor profile.

  1. Remove the AppArmor definition from the kernel:

    tux > sudo apparmor_parser -R /etc/apparmor.d/PROFILE
  2. Remove the definition file:

    tux > sudo rm /etc/apparmor.d/PROFILE
        tux > sudo rm /var/lib/apparmor/cache/PROFILE

24.7 Two Methods of Profiling

Given the syntax for AppArmor profiles in Chapter 21, Profile Components and Syntax, you could create profiles without using the tools. However, the effort involved would be substantial. To avoid such a situation, use the AppArmor tools to automate the creation and refinement of profiles.

There are two ways to approach AppArmor profile creation. Tools are available for both methods.

Stand-Alone Profiling

A method suitable for profiling small applications that have a finite runtime, such as user client applications like mail clients. For more information, refer to Section 24.7.1, “Stand-Alone Profiling”.

Systemic Profiling

A method suitable for profiling many programs at once and for profiling applications that may run for days, weeks, or continuously across reboots, such as network server applications like Web servers and mail servers. For more information, refer to Section 24.7.2, “Systemic Profiling”.

Automated profile development becomes more manageable with the AppArmor tools:

  1. Decide which profiling method suits your needs.

  2. Perform a static analysis. Run either aa-genprof or aa-autodep, depending on the profiling method chosen.

  3. Enable dynamic learning. Activate learning mode for all profiled programs.

24.7.1 Stand-Alone Profiling

Stand-alone profile generation and improvement is managed by a program called aa-genprof. This method is easy because aa-genprof takes care of everything, but is limited because it requires aa-genprof to run for the entire duration of the test run of your program (you cannot reboot the machine while you are still developing your profile).

To use aa-genprof for the stand-alone method of profiling, refer to Section 24.7.3.8, “aa-genprof—Generating Profiles”.

24.7.2 Systemic Profiling

This method is called systemic profiling because it updates all of the profiles on the system at once, rather than focusing on the one or few targeted by aa-genprof or stand-alone profiling. With systemic profiling, profile construction and improvement are somewhat less automated, but more flexible. This method is suitable for profiling long-running applications whose behavior continues after rebooting, or many programs at once.

Build an AppArmor profile for a group of applications as follows:

  1. Create profiles for the individual programs that make up your application.

    Although this approach is systemic, AppArmor only monitors those programs with profiles and their children. To get AppArmor to consider a program, you must at least have aa-autodep create an approximate profile for it. To create this approximate profile, refer to Section 24.7.3.1, “aa-autodep—Creating Approximate Profiles”.

  2. Put relevant profiles into learning or complain mode.

    Activate learning or complain mode for all profiled programs by entering

    aa-complain /etc/apparmor.d/*

    in a terminal window while logged in as root. This functionality is also available through the YaST Profile Mode module, described in Section 23.4.2, “Changing the Mode of Individual Profiles”.

    When in learning mode, access requests are not blocked, even if the profile dictates that they should be. This enables you to run through several tests (as shown in Step 3) and learn the access needs of the program so it runs properly. With this information, you can decide how secure to make the profile.

    Refer to Section 24.7.3.2, “aa-complain—Entering Complain or Learning Mode” for more detailed instructions for using learning or complain mode.

  3. Exercise your application.

    Run your application and exercise its functionality. How much to exercise the program is up to you, but you need the program to access each file representing its access needs. Because the execution is not being supervised by aa-genprof, this step can go on for days or weeks and can span complete system reboots.

  4. Analyze the log.

    In systemic profiling, run aa-logprof directly instead of letting aa-genprof run it (as in stand-alone profiling). The general form of aa-logprof is:

    aa-logprof [ -d /path/to/profiles ] [ -f /path/to/logfile ]

    Refer to Section 24.7.3.9, “aa-logprof—Scanning the System Log” for more information about using aa-logprof.

  5. Repeat Step 3 and Step 4.

    This generates optimal profiles. An iterative approach captures smaller data sets that can be trained and reloaded into the policy engine. Subsequent iterations generate fewer messages and run faster.

  6. Edit the profiles.

    You should review the profiles that have been generated. You can open and edit the profiles in /etc/apparmor.d/ using a text editor.

  7. Return to enforce mode.

    This is when the system goes back to enforcing the rules of the profiles, not only logging information. This can be done manually by removing the flags=(complain) text from the profiles or automatically by using the aa-enforce command, which works identically to the aa-complain command, except it sets the profiles to enforce mode. This functionality is also available through the YaST Profile Mode module, described in Section 23.4.2, “Changing the Mode of Individual Profiles”.

    To ensure that all profiles are taken out of complain mode and put into enforce mode, enter aa-enforce /etc/apparmor.d/*.

  8. Re-scan all profiles.

    To have AppArmor re-scan all of the profiles and change the enforcement mode in the kernel, enter systemctl reload apparmor.

24.7.3 Summary of Profiling Tools

All of the AppArmor profiling utilities are provided by the apparmor-utils RPM package and are stored in /usr/sbin. Each tool has a different purpose.

24.7.3.1 aa-autodep—Creating Approximate Profiles

This creates an approximate profile for the program or application selected. You can generate approximate profiles for binary executables and interpreted script programs. The resulting profile is called approximate because it does not necessarily contain all of the profile entries that the program needs to be properly confined by AppArmor. The minimum aa-autodep approximate profile has, at minimum, a base include directive, which contains basic profile entries needed by most programs. For certain types of programs, aa-autodep generates a more expanded profile. The profile is generated by recursively calling ldd(1) on the executables listed on the command line.

To generate an approximate profile, use the aa-autodep program. The program argument can be either the simple name of the program, which aa-autodep finds by searching your shell's path variable, or it can be a fully qualified path. The program itself can be of any type (ELF binary, shell script, Perl script, etc.). aa-autodep generates an approximate profile to improve through the dynamic profiling that follows.

The resulting approximate profile is written to the /etc/apparmor.d directory using the AppArmor profile naming convention of naming the profile after the absolute path of the program, replacing the forward slash (/) characters in the path with period (.) characters. The general syntax of aa-autodep is to enter the following in a terminal window when logged in as root:

aa-autodep [ -d /PATH/TO/PROFILES ] [PROGRAM1 PROGRAM2...]

If you do not enter the program name or names, you are prompted for them. /path/to/profiles overrides the default location of /etc/apparmor.d, should you keep profiles in a location other than the default.

To begin profiling, you must create profiles for each main executable service that is part of your application (anything that might start without being a child of another program that already has a profile). Finding all such programs depends on the application in question. Here are several strategies for finding such programs:

Directories

If all the programs to profile are in one directory and there are no other programs in that directory, the simple command aa-autodep /path/to/your/programs/* creates basic profiles for all programs in that directory.

pstree -p

You can run your application and use the standard Linux pstree command to find all processes running. Then manually hunt down the location of these programs and run the aa-autodep for each one. If the programs are in your path, aa-autodep finds them for you. If they are not in your path, the standard Linux command find might be helpful in finding your programs. Execute find / -name ' MY_APPLICATION' -print to determine an application's path (MY_APPLICATION being an example application). You may use wild cards if appropriate.

24.7.3.2 aa-complain—Entering Complain or Learning Mode

The complain or learning mode tool (aa-complain) detects violations of AppArmor profile rules, such as the profiled program accessing files not permitted by the profile. The violations are permitted, but also logged. To improve the profile, turn complain mode on, run the program through a suite of tests to generate log events that characterize the program's access needs, then postprocess the log with the AppArmor tools to transform log events into improved profiles.

Manually activating complain mode (using the command line) adds a flag to the top of the profile so that /bin/foo becomes /bin/foo flags=(complain). To use complain mode, open a terminal window and enter one of the following lines as root:

  • If the example program (PROGRAM1) is in your path, use:

    aa-complain [PROGRAM1 PROGRAM2 ...]
  • If the program is not in your path, specify the entire path as follows:

    aa-complain /sbin/PROGRAM1
  • If the profiles are not in /etc/apparmor.d, use the following to override the default location:

    aa-complain /path/to/profiles/PROGRAM1
  • Specify the profile for /sbin/program1 as follows:

    aa-complain /etc/apparmor.d/sbin.PROGRAM1

Each of the above commands activates the complain mode for the profiles or programs listed. If the program name does not include its entire path, aa-complain searches $PATH for the program. For example, aa-complain /usr/sbin/* finds profiles associated with all of the programs in /usr/sbin and puts them into complain mode. aa-complain /etc/apparmor.d/* puts all of the profiles in /etc/apparmor.d into complain mode.

Tip
Tip: Toggling Profile Mode with YaST

YaST offers a graphical front-end for toggling complain and enforce mode. See Section 23.4.2, “Changing the Mode of Individual Profiles” for information.

24.7.3.3 aa-decode—Decoding Hex-encoded Strings in AppArmor Log Files

aa-decode will decode hex-encoded strings in the AppArmor log output. It can also process the audit log on standard input, convert any hex-encoded AppArmor log entries, and display them on standard output.

24.7.3.4 aa-disable—Disabling an AppArmor Security Profile

Use aa-disable to disable the enforcement mode for one or more AppArmor profiles. This command will unload the profile from the kernel, and prevent the profile from being loaded on AppArmor start-up. Use aa-enforce or aa-complain utilities to change this behavior.

24.7.3.5 aa-easyprof—Easy Profile Generation

aa-easyprof provides an easy-to-use interface for AppArmor profile generation. aa-easyprof supports the use of templates and profile groups to quickly profile an application. While aa-easyprof can help with profile generation, its utility is dependent on the quality of the templates, profile groups and abstractions used. Also, this tool may create a profile that is less restricted than when creating a profile manually or with aa-genprof and aa-logprof.

For more information, see the man page of aa-easyprof (8).

24.7.3.6 aa-enforce—Entering Enforce Mode

The enforce mode detects violations of AppArmor profile rules, such as the profiled program accessing files not permitted by the profile. The violations are logged and not permitted. The default is for enforce mode to be enabled. To log the violations only, but still permit them, use complain mode.

Manually activating enforce mode (using the command line) removes the complain flag from the top of the profile so that /bin/foo flags=(complain) becomes /bin/foo. To use enforce mode, open a terminal window and enter one of the following lines as root.

  • If the example program (PROGRAM1) is in your path, use:

    aa-enforce [PROGRAM1 PROGRAM2 ...]
  • If the program is not in your path, specify the entire path, as follows:

    aa-enforce /sbin/PROGRAM1
  • If the profiles are not in /etc/apparmor.d, use the following to override the default location:

    aa-enforce -d /path/to/profiles/     program1
  • Specify the profile for /sbin/program1 as follows:

    aa-enforce /etc/apparmor.d/sbin.PROGRAM1

Each of the above commands activates the enforce mode for the profiles and programs listed.

If you do not enter the program or profile names, you are prompted to enter one. /path/to/profiles overrides the default location of /etc/apparmor.d.

The argument can be either a list of programs or a list of profiles. If the program name does not include its entire path, aa-enforce searches $PATH for the program.

Tip
Tip: Toggling Profile Mode with YaST

YaST offers a graphical front-end for toggling complain and enforce mode. See Section 23.4.2, “Changing the Mode of Individual Profiles” for information.

24.7.3.7 aa-exec—Confining a Program with the Specified Profile

Use aa-exec to launch a program confined by a specified profile and/or profile namespace. If both a profile and namespace are specified, the program will be confined by the profile in the new namespace. If only a profile namespace is specified, the profile name of the current confinement will be used. If neither a profile nor namespace is specified, the command will be run using the standard profile attachment—as if you did not use the aa-exec command.

For more information on the command's options, see its manual page man 8 aa-exec.

24.7.3.8 aa-genprof—Generating Profiles

aa-genprof is AppArmor's profile generating utility. It runs aa-autodep on the specified program, creating an approximate profile (if a profile does not already exist for it), sets it to complain mode, reloads it into AppArmor, marks the log, and prompts the user to execute the program and exercise its functionality. Its syntax is as follows:

aa-genprof [ -d /path/to/profiles ]  PROGRAM

To create a profile for the Apache Web server program httpd2-prefork, do the following as root:

  1. Enter systemctl stop apache2.

  2. Next, enter aa-genprof httpd2-prefork.

    Now aa-genprof does the following:

    1. Resolves the full path of httpd2-prefork using your shell's path variables. You can also specify a full path. On SUSE Linux Enterprise Server, the default full path is /usr/sbin/httpd2-prefork.

    2. Checks to see if there is an existing profile for httpd2-prefork. If there is one, it updates it. If not, it creates one using the aa-autodep as described in Section 24.7.3, “Summary of Profiling Tools”.

    3. Puts the profile for this program into learning or complain mode so that profile violations are logged, but are permitted to proceed. A log event looks like this (see /var/log/audit/audit.log):

      type=APPARMOR_ALLOWED msg=audit(1189682639.184:20816): \
      apparmor="DENIED" operation="file_mmap" parent=2692 \
      profile="/usr/sbin/httpd2-prefork//HANDLING_UNTRUSTED_INPUT" \
      name="/var/log/apache2/access_log-20140116" pid=28730 comm="httpd2-prefork" \
      requested_mask="::r" denied_mask="::r" fsuid=30 ouid=0

      If you are not running the audit daemon, the AppArmor events are logged directly to systemd journal (see Chapter 15, journalctl: Query the systemd Journal):

      Sep 13 13:20:30 K23 kernel: audit(1189682430.672:20810): \
      apparmor="DENIED" operation="file_mmap" parent=2692 \
      profile="/usr/sbin/httpd2-prefork//HANDLING_UNTRUSTED_INPUT" \
      name="/var/log/apache2/access_log-20140116" pid=28730 comm="httpd2-prefork" \
      requested_mask="::r" denied_mask="::r" fsuid=30 ouid=0

      They also can be viewed using the dmesg command:

      audit(1189682430.672:20810): apparmor="DENIED" \
      operation="file_mmap" parent=2692 \
      profile="/usr/sbin/httpd2-prefork//HANDLING_UNTRUSTED_INPUT" \
      name="/var/log/apache2/access_log-20140116" pid=28730 comm="httpd2-prefork" \
      requested_mask="::r" denied_mask="::r" fsuid=30 ouid=0
    4. Marks the log with a beginning marker of log events to consider. For example:

      Sep 13 17:48:52 figwit root: GenProf: e2ff78636296f16d0b5301209a04430d
  3. When prompted by the tool, run the application to profile in another terminal window and perform as many of the application functions as possible. Thus, the learning mode can log the files and directories to which the program requires access to function properly. For example, in a new terminal window, enter systemctl start apache2.

  4. Select from the following options that are available in the aa-genprof terminal window after you have executed the program function:

    • S runs aa-genprof on the system log from where it was marked when aa-genprof was started and reloads the profile. If system events exist in the log, AppArmor parses the learning mode log files. This generates a series of questions that you must answer to guide aa-genprof in generating the security profile.

    • F exits the tool.

    Note
    Note

    If requests to add hats appear, proceed to Chapter 25, Profiling Your Web Applications Using ChangeHat.

  5. Answer two types of questions:

    Each of these categories results in a series of questions that you must answer to add the resource or program to the profile. Example 24.1, “Learning Mode Exception: Controlling Access to Specific Resources” and Example 24.2, “Learning Mode Exception: Defining Permissions for an Entry” provide examples of each one. Subsequent steps describe your options in answering these questions.

    • Dealing with execute accesses is complex. You must decide how to proceed with this entry regarding which execute permission type to grant to this entry:

      Example 24.1: Learning Mode Exception: Controlling Access to Specific Resources
      Reading log entries from /var/log/audit/audit.log.
      Updating AppArmor profiles in /etc/apparmor.d.
      
      Profile:  /usr/sbin/xinetd
      Program:  xinetd
      Execute:  /usr/lib/cups/daemon/cups-lpd
      Severity: unknown
      
      (I)nherit / (P)rofile / (C)hild / (N)ame / (U)nconfined / (X)ix / (D)eny / Abo(r)t / (F)inish
      Inherit (ix)

      The child inherits the parent's profile, running with the same access controls as the parent. This mode is useful when a confined program needs to call another confined program without gaining the permissions of the target's profile or losing the permissions of the current profile. This mode is often used when the child program is a helper application, such as the /usr/bin/mail client using less as a pager.

      Profile (px/Px)

      The child runs using its own profile, which must be loaded into the kernel. If the profile is not present, attempts to execute the child fail with permission denied. This is most useful if the parent program is invoking a global service, such as DNS lookups or sending mail with your system's MTA.

      Choose the profile with clean exec (Px) option to scrub the environment of environment variables that could modify execution behavior when passed to the child process.

      Child (cx/Cx)

      Sets up a transition to a subprofile. It is like px/Px transition, except to a child profile.

      Choose the profile with clean exec (Cx) option to scrub the environment of environment variables that could modify execution behavior when passed to the child process.

      Unconfined (ux/Ux)

      The child runs completely unconfined without any AppArmor profile applied to the executed resource.

      Choose the unconfined with clean exec (Ux) option to scrub the environment of environment variables that could modify execution behavior when passed to the child process. Note that running unconfined profiles introduces a security vulnerability that could be used to evade AppArmor. Only use it as a last resort.

      mmap (m)

      This permission denotes that the program running under the profile can access the resource using the mmap system call with the flag PROT_EXEC. This means that the data mapped in it can be executed. You are prompted to include this permission if it is requested during a profiling run.

      Deny

      Adds a deny rule to the profile, and permanently prevents the program from accessing the specified directory path entries. AppArmor then continues to the next event.

      Abort

      Aborts aa-logprof, losing all rule changes entered so far and leaving all profiles unmodified.

      Finish

      Closes aa-logprof, saving all rule changes entered so far and modifying all profiles.

    • Example 24.2, “Learning Mode Exception: Defining Permissions for an Entry” shows AppArmor suggest allowing a globbing pattern /var/run/nscd/* for reading, then using an abstraction to cover common Apache-related access rules.

      Example 24.2: Learning Mode Exception: Defining Permissions for an Entry
      Profile:  /usr/sbin/httpd2-prefork
      Path:     /var/run/nscd/dbSz9CTr
      Mode:     r
      Severity: 3
      
        1 - /var/run/nscd/dbSz9CTr
       [2 - /var/run/nscd/*]
      
      (A)llow / [(D)eny] / (G)lob / Glob w/(E)xt / (N)ew / Abo(r)t / (F)inish / (O)pts
      Adding /var/run/nscd/* r to profile.
      
      Profile:  /usr/sbin/httpd2-prefork
      Path:     /proc/11769/attr/current
      Mode:     w
      Severity: 9
      
       [1 - #include <abstractions/apache2-common>]
        2 - /proc/11769/attr/current
        3 - /proc/*/attr/current
      
      (A)llow / [(D)eny] / (G)lob / Glob w/(E)xt / (N)ew / Abo(r)t / (F)inish / (O)pts
      Adding #include <abstractions/apache2-common> to profile.

      AppArmor provides one or more paths or includes. By entering the option number, select the desired options then proceed to the next step.

      Note
      Note

      Not all of these options are always presented in the AppArmor menu.

      #include

      This is the section of an AppArmor profile that refers to an include file, which procures access permissions for programs. By using an include, you can give the program access to directory paths or files that are also required by other programs. Using includes can reduce the size of a profile. It is good practice to select includes when suggested.

      Globbed Version

      This is accessed by selecting Glob as described in the next step. For information about globbing syntax, refer to Section 21.6, “Profile Names, Flags, Paths, and Globbing”.

      Actual Path

      This is the literal path to which the program needs access so that it can run properly.

      After you select the path or include, process it as an entry into the AppArmor profile by selecting Allow or Deny. If you are not satisfied with the directory path entry as it is displayed, you can also Glob it.

      The following options are available to process the learning mode entries and build the profile:

      Select Enter

      Allows access to the selected directory path.

      Allow

      Allows access to the specified directory path entries. AppArmor suggests file permission access. For more information, refer to Section 21.7, “File Permission Access Modes”.

      Deny

      Prevents the program from accessing the specified directory path entries. AppArmor then continues to the next event.

      New

      Prompts you to enter your own rule for this event, allowing you to specify a regular expression. If the expression does not actually satisfy the event that prompted the question in the first place, AppArmor asks for confirmation and lets you reenter the expression.

      Glob

      Select a specific path or create a general rule using wild cards that match a broader set of paths. To select any of the offered paths, enter the number that is printed in front of the path then decide how to proceed with the selected item.

      For more information about globbing syntax, refer to Section 21.6, “Profile Names, Flags, Paths, and Globbing”.

      Glob w/Ext

      This modifies the original directory path while retaining the file name extension. For example, /etc/apache2/file.ext becomes /etc/apache2/*.ext, adding the wild card (asterisk) in place of the file name. This allows the program to access all files in the suggested directory that end with the .ext extension.

      Abort

      Aborts aa-logprof, losing all rule changes entered so far and leaving all profiles unmodified.

      Finish

      Closes aa-logprof, saving all rule changes entered so far and modifying all profiles.

  6. To view and edit your profile using vi, enter vi /etc/apparmor.d/ PROFILENAME in a terminal window. To enable syntax highlighting when editing an AppArmor profile in vim, use the commands :syntax on then :set syntax=apparmor. For more information about vim and syntax highlighting, refer to Section 24.7.3.14, “apparmor.vim”.

  7. Restart AppArmor and reload the profile set including the newly created one using the systemctl reload apparmor command.

Like the graphical front-end for building AppArmor profiles, the YaST Add Profile Wizard, aa-genprof also supports the use of the local profile repository under /etc/apparmor/profiles/extras and the remote AppArmor profile repository.

To use a profile from the local repository, proceed as follows:

  1. Start aa-genprof as described above.

    If aa-genprof finds an inactive local profile, the following lines appear on your terminal window:

    Profile: /usr/bin/opera
    
     [1 - Inactive local profile for /usr/bin/opera]
    
    [(V)iew Profile] / (U)se Profile / (C)reate New Profile / Abo(r)t / (F)inish
  2. To use this profile, press U (Use Profile) and follow the profile generation procedure outlined above.

    To examine the profile before activating it, press V (View Profile).

    To ignore the existing profile, press C (Create New Profile) and follow the profile generation procedure outlined above to create the profile from scratch.

  3. Leave aa-genprof by pressing F (Finish) when you are done and save your changes.

24.7.3.9 aa-logprof—Scanning the System Log

aa-logprof is an interactive tool used to review the complain and enforce mode events found in the log entries in /var/log/audit/audit.log, or directly in the systemd journal (see Chapter 15, journalctl: Query the systemd Journal), and generate new entries in AppArmor security profiles.

When you run aa-logprof, it begins to scan the log files produced in complain and enforce mode and, if there are new security events that are not covered by the existing profile set, it gives suggestions for modifying the profile. aa-logprof uses this information to observe program behavior.

If a confined program forks and executes another program, aa-logprof sees this and asks the user which execution mode should be used when launching the child process. The execution modes ix, px, Px, ux, Ux, cx, Cx, and named profiles, are options for starting the child process. If a separate profile exists for the child process, the default selection is Px. If one does not exist, the profile defaults to ix. Child processes with separate profiles have aa-autodep run on them and are loaded into AppArmor, if it is running.

When aa-logprof exits, profiles are updated with the changes. If AppArmor is active, the updated profiles are reloaded and, if any processes that generated security events are still running in the null-XXXX profiles (unique profiles temporarily created in complain mode), those processes are set to run under their proper profiles.

To run aa-logprof, enter aa-logprof into a terminal window while logged in as root. The following options can be used for aa-logprof:

aa-logprof -d/path/to/profile/directory/

Specifies the full path to the location of the profiles if the profiles are not located in the standard directory, /etc/apparmor.d/.

aa-logprof -f/path/to/logfile/

Specifies the full path to the location of the log file if the log file is not located in the default directory or /var/log/audit/audit.log.

aa-logprof -m "string marker in logfile"

Marks the starting point for aa-logprof to look in the system log. aa-logprof ignores all events in the system log before the specified mark. If the mark contains spaces, it must be surrounded by quotes to work correctly. For example:

aa-logprof -m "17:04:21"

or

aa-logprof -m e2ff78636296f16d0b5301209a04430d

aa-logprof scans the log, asking you how to handle each logged event. Each question presents a numbered list of AppArmor rules that can be added by pressing the number of the item on the list.

By default, aa-logprof looks for profiles in /etc/apparmor.d/. Often running aa-logprof as root is enough to update the profile. However, there might be times when you need to search archived log files, such as if the program exercise period exceeds the log rotation window (when the log file is archived and a new log file is started). If this is the case, you can enter zcat -f `ls -1tr /path/to/logfile*` | aa-logprof -f -.

24.7.3.10 aa-logprof Example 1

The following is an example of how aa-logprof addresses httpd2-prefork accessing the file /etc/group. [] indicates the default option.

In this example, the access to /etc/group is part of httpd2-prefork accessing name services. The appropriate response is 1, which includes a predefined set of AppArmor rules. Selecting 1 to #include the name service package resolves all of the future questions pertaining to DNS lookups and makes the profile less brittle in that any changes to DNS configuration and the associated name service profile package can be made once, rather than needing to revise many profiles.

Profile:  /usr/sbin/httpd2-prefork
Path:     /etc/group
New Mode: r

[1 - #include <abstractions/nameservice>]
 2 - /etc/group
[(A)llow] / (D)eny / (N)ew / (G)lob / Glob w/(E)xt / Abo(r)t / (F)inish

Select one of the following responses:

Select Enter

Triggers the default action, which is, in this example, allowing access to the specified directory path entry.

Allow

Allows access to the specified directory path entries. AppArmor suggests file permission access. For more information about this, refer to Section 21.7, “File Permission Access Modes”.

Deny

Permanently prevents the program from accessing the specified directory path entries. AppArmor then continues to the next event.

New

Prompts you to enter your own rule for this event, allowing you to specify whatever form of regular expression you want. If the expression entered does not actually satisfy the event that prompted the question in the first place, AppArmor asks for confirmation and lets you reenter the expression.

Glob

Select either a specific path or create a general rule using wild cards that matches on a broader set of paths. To select any of the offered paths, enter the number that is printed in front of the paths then decide how to proceed with the selected item.

For more information about globbing syntax, refer to Section 21.6, “Profile Names, Flags, Paths, and Globbing”.

Glob w/Ext

This modifies the original directory path while retaining the file name extension. For example, /etc/apache2/file.ext becomes /etc/apache2/*.ext, adding the wild card (asterisk) in place of the file name. This allows the program to access all files in the suggested directory that end with the .ext extension.

Abort

Aborts aa-logprof, losing all rule changes entered so far and leaving all profiles unmodified.

Finish

Closes aa-logprof, saving all rule changes entered so far and modifying all profiles.

24.7.3.11 aa-logprof Example 2

For example, when profiling vsftpd, see this question:

Profile:  /usr/sbin/vsftpd
Path:     /y2k.jpg

New Mode: r

[1 - /y2k.jpg]

(A)llow / [(D)eny] / (N)ew / (G)lob / Glob w/(E)xt / Abo(r)t / (F)inish

Several items of interest appear in this question. First, note that vsftpd is asking for a path entry at the top of the tree, even though vsftpd on SUSE Linux Enterprise Server serves FTP files from /srv/ftp by default. This is because vsftpd uses chroot and, for the portion of the code inside the chroot jail, AppArmor sees file accesses in terms of the chroot environment rather than the global absolute path.

The second item of interest is that you should grant FTP read access to all JPEG files in the directory, so you could use Glob w/Ext and use the suggested path of /*.jpg. Doing so collapses all previous rules granting access to individual .jpg files and forestalls any future questions pertaining to access to .jpg files.

Finally, you should grant more general access to FTP files. If you select Glob in the last entry, aa-logprof replaces the suggested path of /y2k.jpg with /*. Alternatively, you should grant even more access to the entire directory tree, in which case you could use the New path option and enter /**.jpg (which would grant access to all .jpg files in the entire directory tree) or /** (which would grant access to all files in the directory tree).

These items deal with read accesses. Write accesses are similar, except that it is good policy to be more conservative in your use of regular expressions for write accesses. Dealing with execute accesses is more complex. Find an example in Example 24.1, “Learning Mode Exception: Controlling Access to Specific Resources”.

In the following example, the /usr/bin/mail mail client is being profiled and aa-logprof has discovered that /usr/bin/mail executes /usr/bin/less as a helper application to page long mail messages. Consequently, it presents this prompt:

/usr/bin/nail -> /usr/bin/less
(I)nherit / (P)rofile / (C)hild / (N)ame / (U)nconfined / (X)ix / (D)eny
Note
Note

The actual executable file for /usr/bin/mail turns out to be /usr/bin/nail, which is not a typographical error.

The program /usr/bin/less appears to be a simple one for scrolling through text that is more than one screen long and that is in fact what /usr/bin/mail is using it for. However, less is actually a large and powerful program that uses many other helper applications, such as tar and rpm.

Tip
Tip

Run less on a tar file or an RPM file and it shows you the inventory of these containers.

You do not want to run rpm automatically when reading mail messages (that leads directly to a Microsoft* Outlook–style virus attack, because RPM has the power to install and modify system programs), so, in this case, the best choice is to use Inherit. This results in the less program executed from this context running under the profile for /usr/bin/mail. This has two consequences:

  • You need to add all of the basic file accesses for /usr/bin/less to the profile for /usr/bin/mail.

  • You can avoid adding the helper applications, such as tar and rpm, to the /usr/bin/mail profile so that when /usr/bin/mail runs /usr/bin/less in this context, the less program is far less dangerous than it would be without AppArmor protection. Another option is to use the Cx execute modes. For more information on execute modes, see Section 21.8, “Execute Modes”.

In other circumstances, you might instead want to use the Profile option. This has the following effects on aa-logprof:

  • The rule written into the profile uses px/Px, which forces the transition to the child's own profile.

  • aa-logprof constructs a profile for the child and starts building it, in the same way that it built the parent profile, by assigning events for the child process to the child's profile and asking the aa-logprof user questions. The profile will also be applied if you run the child as a stand-alone program.

If a confined program forks and executes another program, aa-logprof sees this and asks the user which execution mode should be used when launching the child process. The execution modes of inherit, profile, unconfined, child, named profile, or an option to deny the execution are presented.

If a separate profile exists for the child process, the default selection is profile. If a profile does not exist, the default is inherit. The inherit option, or ix, is described in Section 21.7, “File Permission Access Modes”.

The profile option indicates that the child program should run in its own profile. A secondary question asks whether to sanitize the environment that the child program inherits from the parent. If you choose to sanitize the environment, this places the execution modifier Px in your AppArmor profile. If you select not to sanitize, px is placed in the profile and no environment sanitizing occurs. The default for the execution mode is Px if you select profile execution mode.

The unconfined execution mode is not recommended and should only be used in cases where there is no other option to generate a profile for a program reliably. Selecting unconfined opens a warning dialog asking for confirmation of the choice. If you are sure and choose Yes, a second dialog ask whether to sanitize the environment. To use the execution mode Ux in your profile, select Yes. To use the execution mode ux in your profile instead, select No. The default value selected is Ux for unconfined execution mode.

Important
Important: Running Unconfined

Selecting ux or Ux is very dangerous and provides no enforcement of policy (from a security perspective) of the resulting execution behavior of the child program.

24.7.3.12 aa-unconfined—Identifying Unprotected Processes

The aa-unconfined command examines open network ports on your system, compares that to the set of profiles loaded on your system, and reports network services that do not have AppArmor profiles. It requires root privileges and that it not be confined by an AppArmor profile.

aa-unconfined must be run as root to retrieve the process executable link from the /proc file system. This program is susceptible to the following race conditions:

  • An unlinked executable is mishandled

  • A process that dies between netstat(8) and further checks is mishandled

Note
Note

This program lists processes using TCP and UDP only. In short, this program is unsuitable for forensics use and is provided only as an aid to profiling all network-accessible processes in the lab.

24.7.3.13 aa-notify

aa-notify is a handy utility that displays AppArmor notifications in your desktop environment. This is very convenient if you do not want to inspect the AppArmor log file, but rather let the desktop inform you about events that violate the policy. To enable AppArmor desktop notifications, run aa-notify:

sudo aa-notify -p -u USERNAME --display DISPLAY_NUMBER

where USERNAME is your user name under which you are logged in, and DISPLAY_NUMBER is the X Window display number you are currently using, such as :0. The process is run in the background, and shows a notification each time a deny event happens.

Tip
Tip

The active X Window display number is saved in the $DISPLAY variable, so you can use --display $DISPLAY to avoid finding out the current display number.

aa-notify Message in GNOME
Figure 24.1: aa-notify Message in GNOME

With the -s DAYS option, you can also configure aa-notify to display a summary of notifications for the specified number of past days. For more information on aa-notify, see its man page man 8 aa-notify.

24.7.3.14 apparmor.vim

A syntax highlighting file for the vim text editor highlights various features of an AppArmor profile with colors. Using vim and the AppArmor syntax mode for vim, you can see the semantic implications of your profiles with color highlighting. Use vim to view and edit your profile by typing vim at a terminal window.

To enable the syntax coloring when you edit an AppArmor profile in vim, use the commands :syntax on then :set syntax=apparmor. To make sure vim recognizes the edited file type correctly as an AppArmor profile, add

# vim:ft=apparmor

at the end of the profile.

Tip
Tip

vim comes with AppArmor highlighting automatically enabled for files in /etc/apparmor.d/.

When you enable this feature, vim colors the lines of the profile for you:

Blue

Comments

White

Ordinary read access lines

Brown

Capability statements and complain flags

Yellow

Lines that grant write access

Green

Lines that grant execute permission (either ix or px)

Red

Lines that grant unconfined access (ux)

Red background

Syntax errors that will not load properly into the AppArmor modules

Use the apparmor.vim and vim man pages and the :help syntax from within the vim editor for further vim help about syntax highlighting. The AppArmor syntax is stored in /usr/share/vim/current/syntax/apparmor.vim.

24.8 Important File Names and Directories

The following list contains the most important files and directories used by the AppArmor framework. If you intend to manage and troubleshoot your profiles manually, make sure that you know about these files and directories:

/sys/kernel/security/apparmor/profiles

Virtualized file representing the currently loaded set of profiles.

/etc/apparmor/

Location of AppArmor configuration files.

/etc/apparmor/profiles/extras/

A local repository of profiles shipped with AppArmor, but not enabled by default.

/etc/apparmor.d/

Location of profiles, named with the convention of replacing the / in paths with . (not for the root /) so profiles are easier to manage. For example, the profile for the program /usr/sbin/ntpd is named usr.sbin.ntpd.

/etc/apparmor.d/abstractions/

Location of abstractions.

/etc/apparmor.d/program-chunks/

Location of program chunks.

/proc/*/attr/current

Check this file to review the confinement status of a process and the profile that is used to confine the process. The ps auxZ command retrieves this information automatically.

25 Profiling Your Web Applications Using ChangeHat

  • Filename: apparmor_changehat.xml
  • ID: cha.apparmor.hat

An AppArmor® profile represents the security policy for an individual program instance or process. It applies to an executable program, but if a portion of the program needs different access permissions than other portions, the program can change hats to use a different security context, distinctive from the access of the main program. This is known as a hat or subprofile.

ChangeHat enables programs to change to or from a hat within an AppArmor profile. It enables you to define security at a finer level than the process. This feature requires that each application be made ChangeHat-aware, meaning that it is modified to make a request to the AppArmor module to switch security domains at specific times during the application execution. One example of a ChangeHat-aware application is the Apache Web server.

A profile can have an arbitrary number of subprofiles, but there are only two levels: a subprofile cannot have further child profiles. A subprofile is written as a separate profile. Its name consists of the name of the containing profile followed by the subprofile name, separated by a ^.

Subprofiles are either stored in the same file as the parent profile, or in a separate file. The latter case is recommended on sites with many hats—it allows the policy caching to handle changes at the per hat level. If all the hats are in the same file as the parent profile, then the parent profile and all hats must be recompiled.

An external subprofile that is going to be used as a hat, must begin with the word hat or the ^ character.

The following two subprofiles cannot be used as a hat:

/foo//bar { }

or

profile /foo//bar { }

While the following two are treated as hats:

^/foo//bar { }

or

hat /foo//bar { } # this syntax is not highlighted in vim

Note that the security of hats is considerably weaker than that of full profiles. Using certain types of bugs in a program, an attacker may be able to escape from a hat into the containing profile. This is because the security of hats is determined by a secret key handled by the containing process, and the code running in the hat must not have access to the key. Thus, change_hat is most useful with application servers, where a language interpreter (such as PERL, PHP, or Java) is isolating pieces of code such that they do not have direct access to the memory of the containing process.

The rest of this chapter describes using change_hat with Apache, to contain Web server components run using mod_perl and mod_php. Similar approaches can be used with any application server by providing an application module similar to the mod_apparmor described next in Section 25.1.2, “Location and Directory Directives”.

Tip
Tip: For More Information

For more information, see the change_hat man page.

25.1 Configuring Apache for mod_apparmor

AppArmor provides a mod_apparmor module (package apache2-mod-apparmor) for the Apache program. This module makes the Apache Web server ChangeHat aware. Install it along with Apache.

When Apache is ChangeHat-aware, it checks for the following customized AppArmor security profiles in the order given for every URI request that it receives.

  • URI-specific hat. For example, ^www_app_name/templates/classic/images/bar_left.gif

  • DEFAULT_URI

  • HANDLING_UNTRUSTED_INPUT

Note
Note: Apache Configuration

If you install apache2-mod-apparmor, make sure the module is enabled, and then restart Apache by executing the following command:

a2enmod apparmor && sudo systemctl reload apache2

Apache is configured by placing directives in plain text configuration files. The main configuration file is usually /etc/apache2/httpd.conf. When you compile Apache, you can indicate the location of this file. Directives can be placed in any of these configuration files to alter the way Apache behaves. When you make changes to the main configuration files, you need to reload Apache with sudo systemctl reload apache2, so the changes are recognized.

25.1.1 Virtual Host Directives

<VirtualHost> and </VirtualHost> directives are used to enclose a group of directives that will apply only to a particular virtual host. For more information on Apache virtual host directives, refer to http://httpd.apache.org/docs/2.4/en/mod/core.html#virtualhost.

The ChangeHat-specific configuration keyword is AADefaultHatName. It is used similarly to AAHatName, for example, AADefaultHatName My_Funky_Default_Hat.

It allows you to specify a default hat to be used for virtual hosts and other Apache server directives, so that you can have different defaults for different virtual hosts. This can be overridden by the AAHatName directive and is checked for only if there is not a matching AAHatName or hat named by the URI. If the AADefaultHatName hat does not exist, it falls back to the DEFAULT_URI hat if it exists/

If none of those are matched, it goes back to the parent Apache hat.

25.1.2 Location and Directory Directives

Location and directory directives specify hat names in the program configuration file so the Apache calls the hat regarding its security. For Apache, you can find documentation about the location and directory directives at http://httpd.apache.org/docs/2.4/en/sections.html.

The location directive example below specifies that, for a given location, mod_apparmor should use a specific hat:

<Location /foo/>
  AAHatName MY_HAT_NAME
</Location>

This tries to use MY_HAT_NAME for any URI beginning with /foo/ (/foo/, /foo/bar, /foo/cgi/path/blah_blah/blah, etc.).

The directory directive works similarly to the location directive, except it refers to a path in the file system as in the following example:

<Directory "/srv/www/www.example.org/docs">
  # Note lack of trailing slash
  AAHatName example.org
</Directory>

25.2 Managing ChangeHat-Aware Applications

In the previous section you learned about mod_apparmor and the way it helps you to secure a specific Web application. This section walks you through a real-life example of creating a hat for a Web application, and using AppArmor's change_hat feature to secure it. Note that this chapter focuses on AppArmor's command line tools, as YaST's AppArmor module has limited functionality.

25.2.1 With AppArmor's Command Line Tools

For illustration purposes, let us choose the Web application called Adminer (http://www.adminer.org/en/). It is a full-featured SQL database management tool written in PHP, yet consisting of a single PHP file. For Adminer to work, you need to set up an Apache Web server, PHP and its Apache module, and one of the database drivers available for PHP—MariaDB in this example. You can install the required packages with

zypper in apache2 apache2-mod_apparmor apache2-mod_php5 php5 php5-mysql

To set up the Web environment for running Adminer, follow these steps:

Procedure 25.1: Setting Up a Web Server Environment
  1. Make sure apparmor and php5 modules are enabled for Apache. To enable the modules in any case, use:

    a2enmod apparmor php5

    and then restart Apache with

    sudo systemctl restart apache2
  2. Make sure MariaDB is running. If unsure, restart it with

    sudo systemctl restart mysql
  3. Download Adminer from http://www.adminer.org, copy it to /srv/www/htdocs/adminer/, and rename it to adminer.php, so that its full path is /srv/www/htdocs/adminer/adminer.php.

  4. Test Adminer in your Web browser by entering http://localhost/adminer/adminer.php in its URI address field. If you installed Adminer to a remote server, replace localhost with the real host name of the server.

    Adminer Login Page
    Figure 25.1: Adminer Login Page
    Tip
    Tip

    If you encounter problems viewing the Adminer login page, try to look for help in the Apache error log /var/log/apache2/error.log. Another reason you cannot access the Web page may be that your Apache is already under AppArmor control and its AppArmor profile is too tight to permit viewing Adminer. Check it with aa-status, and if needed, set Apache temporarily in complain mode with

    aa-complain usr.sbin.httpd2-prefork

After the Web environment for Adminer is ready, you need to configure Apache's mod_apparmor, so that AppArmor can detect accesses to Adminer and change to the specific hat.

Procedure 25.2: Configuring mod_apparmor
  1. Apache has several configuration files under /etc/apache2/ and /etc/apache2/conf.d/. Choose your preferred one and open it in a text editor. In this example, the vim editor is used to create a new configuration file /etc/apache2/conf.d/apparmor.conf.

    vim /etc/apache2/conf.d/apparmor.conf
  2. Copy the following snippet into the edited file.

    <Directory /srv/www/htdocs/adminer>
      AAHatName adminer
    </Directory>

    It tells Apache to let AppArmor know about a change_hat event when the Web user accesses the directory /adminer (and any file/directory inside) in Apache's document root. Remember, we placed the adminer.php application there.

  3. Save the file, close the editor, and restart Apache with

    sudo systemctl restart apache2

Apache now knows about our Adminer and changing a hat for it. It is time to create the related hat for Adminer in the AppArmor configuration. If you do not have an AppArmor profile yet, create one before proceeding. Remember that if your Apache's main binary is /usr/sbin/httpd2-prefork, then the related profile is named /etc/apparmor.d/usr.sbin.httpd2-prefork.

Procedure 25.3: Creating a Hat for Adminer
  1. Open (or create one if it does not exist) the file /etc/apparmor.d/usr.sbin.httpd2-prefork in a text editor. Its contents should be similar to the following:

    #include <tunables/global>
    
    /usr/sbin/httpd2-prefork {
      #include <abstractions/apache2-common>
      #include <abstractions/base>
      #include <abstractions/php5>
    
      capability kill,
      capability setgid,
      capability setuid,
    
      /etc/apache2/** r,
      /run/httpd.pid rw,
      /usr/lib{,32,64}/apache2*/** mr,
      /var/log/apache2/** rw,
    
      ^DEFAULT_URI {
        #include <abstractions/apache2-common>
        /var/log/apache2/** rw,
      }
    
      ^HANDLING_UNTRUSTED_INPUT {
        #include <abstractions/apache2-common>
        /var/log/apache2/** w,
      }
    }
  2. Before the last closing curly bracket (}), insert the following section:

    ^adminer flags=(complain) {
    }

    Note the (complain) addition after the hat name—it tells AppArmor to leave the adminer hat in complain mode. That is because we need to learn the hat profile by accessing Adminer later on.

  3. Save the file, and then restart AppArmor, then Apache.

    systemctl reload apparmor apache2
  4. Check if the adminer hat really is in complain mode.

    # aa-status
    apparmor module is loaded.
    39 profiles are loaded.
    37 profiles are in enforce mode.
    [...]
       /usr/sbin/httpd2-prefork
       /usr/sbin/httpd2-prefork//DEFAULT_URI
       /usr/sbin/httpd2-prefork//HANDLING_UNTRUSTED_INPUT
    [...]
    2 profiles are in complain mode.
       /usr/bin/getopt
       /usr/sbin/httpd2-prefork//adminer
    [...]

    As we can see, the httpd2-prefork//adminer is loaded in complain mode.

Our last task is to find out the right set of rules for the adminer hat. That is why we set the adminer hat into complain mode—the logging facility collects useful information about the access requirements of adminer.php as we use it via the Web browser. aa-logprof then helps us with creating the hat's profile.

Procedure 25.4: Generating Rules for the adminer Hat
  1. Open Adminer in the Web browser. If you installed it locally, then the URI is http://localhost/adminer/adminer.php.

  2. Choose the database engine you want to use (MariaDB in our case), and log in to Adminer using the existing database user name and password. You do not need to specify the database name as you can do so after logging in. Perform any operations with Adminer you like—create a new database, create a new table for it, set user privileges, and so on.

  3. After the short testing of Adminer's user interface, switch back to console and examine the log for collected data.

    # aa-logprof
    Reading log entries from /var/log/messages.
    Updating AppArmor profiles in /etc/apparmor.d.
    Complain-mode changes:
    
    Profile:  /usr/sbin/httpd2-prefork^adminer
    Path:     /dev/urandom
    Mode:     r
    Severity: 3
    
      1 - #include <abstractions/apache2-common>
    [...]
     [8 - /dev/urandom]
    
    [(A)llow] / (D)eny / (G)lob / Glob w/(E)xt / (N)ew / Abo(r)t / (F)inish / (O)pts

    From the aa-logprof message, it is clear that our new adminer hat was correctly detected:

    Profile:  /usr/sbin/httpd2-prefork^adminer

    The aa-logprof command will ask you to pick the right rule for each discovered AppArmor event. Specify the one you want to use, and confirm with Allow. For more information on working with the aa-genprof and aa-logprof interface, see Section 24.7.3.8, “aa-genprof—Generating Profiles”.

    Tip
    Tip

    aa-logprof usually offers several valid rules for the examined event. Some are abstractions—predefined sets of rules affecting a specific common group of targets. Sometimes it is useful to include such an abstraction instead of a direct URI rule:

     1 - #include <abstractions/php5>
     [2 - /var/lib/php5/sess_3jdmii9cacj1e3jnahbtopajl7p064ai242]

    In the example above, it is recommended hitting 1 and confirming with A to allow the abstraction.

  4. After the last change, you will be asked to save the changed profile.

    The following local profiles were changed. Would you like to save them?
     [1 - /usr/sbin/httpd2-prefork]
    
     (S)ave Changes / [(V)iew Changes] / Abo(r)t

    Hit S to save the changes.

  5. Set the profile to enforce mode with aa-enforce

    aa-enforce usr.sbin.httpd2-prefork

    and check its status with aa-status

    # aa-status
    apparmor module is loaded.
    39 profiles are loaded.
    38 profiles are in enforce mode.
    [...]
       /usr/sbin/httpd2-prefork
       /usr/sbin/httpd2-prefork//DEFAULT_URI
       /usr/sbin/httpd2-prefork//HANDLING_UNTRUSTED_INPUT
       /usr/sbin/httpd2-prefork//adminer
    [...]

    As you can see, the //adminer hat jumped from complain to enforce mode.

  6. Try to run Adminer in the Web browser, and if you encounter problems running it, switch it to the complain mode, repeat the steps that previously did not work well, and update the profile with aa-logprof until you are satisfied with the application's functionality.

Note
Note: Hat and Parent Profile Relationship

The profile ^adminer is only available in the context of a process running under the parent profile usr.sbin.httpd2-prefork.

25.2.2 Adding Hats and Entries to Hats in YaST

When you use the Edit Profile dialog (for instructions, refer to Section 23.2, “Editing Profiles”) or when you add a new profile using Manually Add Profile (for instructions, refer to Section 23.1, “Manually Adding a Profile”), you are given the option of adding hats (subprofiles) to your AppArmor profiles. Add a ChangeHat subprofile from the AppArmor Profile Dialog window as in the following.

AppArmor profile dialog
  1. From the AppArmor Profile Dialog window, click Add Entry then select Hat. The EnterHat Name dialog opens:

    Enter hat name
  2. Enter the name of the hat to add to the AppArmor profile. The name is the URI that, when accessed, receives the permissions set in the hat.

  3. Click Create Hat. You are returned to the AppArmor Profile Dialog screen.

  4. After adding the new hat, click Done.

26 Confining Users with pam_apparmor

  • Filename: apparmor_pam.xml
  • ID: cha.apparmor.pam

An AppArmor profile applies to an executable program; if a portion of the program needs different access permissions than other portions need, the program can change hats via change_hat to a different role, also known as a subprofile. The pam_apparmor PAM module allows applications to confine authenticated users into subprofiles based on group names, user names, or a default profile. To accomplish this, pam_apparmor needs to be registered as a PAM session module.

The package pam_apparmor is not installed by default, you can install it using YaST or zypper. Details about how to set up and configure pam_apparmor can be found in /usr/share/doc/packages/pam_apparmor/README after the package has been installed. For details on PAM, refer to Chapter 2, Authentication with PAM.

27 Managing Profiled Applications

  • Filename: apparmor_managing.xml
  • ID: cha.apparmor.managing

After creating profiles and immunizing your applications, SUSE® Linux Enterprise Server becomes more efficient and better protected as long as you perform AppArmor® profile maintenance (which involves analyzing log files, refining your profiles, backing up your set of profiles and keeping it up-to-date). You can deal with these issues before they become a problem by setting up event notification by e-mail, updating profiles from system log entries by running the aa-logprof tool, and dealing with maintenance issues.

27.1 Reacting to Security Event Rejections

When you receive a security event rejection, examine the access violation and determine if that event indicated a threat or was part of normal application behavior. Application-specific knowledge is required to make the determination. If the rejected action is part of normal application behavior, run aa-logprof at the command line.

If the rejected action is not part of normal application behavior, this access should be considered a possible intrusion attempt (that was prevented) and this notification should be passed to the person responsible for security within your organization.

27.2 Maintaining Your Security Profiles

In a production environment, you should plan on maintaining profiles for all of the deployed applications. The security policies are an integral part of your deployment. You should plan on taking steps to back up and restore security policy files, plan for software changes, and allow any needed modification of security policies that your environment dictates.

27.2.1 Backing Up Your Security Profiles

Backing up profiles might save you from having to re-profile all your programs after a disk crash. Also, if profiles are changed, you can easily restore previous settings by using the backed up files.

Back up profiles by copying the profile files to a specified directory.

  1. You should first archive the files into one file. To do this, open a terminal window and enter the following as root:

    tar zclpf profiles.tgz /etc/apparmor.d

    The simplest method to ensure that your security policy files are regularly backed up is to include the directory /etc/apparmor.d in the list of directories that your backup system archives.

  2. You can also use scp or a file manager like Nautilus to store the files on some kind of storage media, the network, or another computer.

27.2.2 Changing Your Security Profiles

Maintenance of security profiles includes changing them if you decide that your system requires more or less security for its applications. To change your profiles in AppArmor, refer to Section 23.2, “Editing Profiles”.

27.2.3 Introducing New Software into Your Environment

When you add a new application version or patch to your system, you should always update the profile to fit your needs. You have several options, depending on your company's software deployment strategy. You can deploy your patches and upgrades into a test or production environment. The following explains how to do this with each method.

If you intend to deploy a patch or upgrade in a test environment, the best method for updating your profiles is to run aa-logprof in a terminal as root. For detailed instructions, refer to Section 24.7.3.9, “aa-logprof—Scanning the System Log”.

If you intend to deploy a patch or upgrade directly into a production environment, the best method for updating your profiles is to monitor the system frequently to determine if any new rejections should be added to the profile and update as needed using aa-logprof. For detailed instructions, refer to Section 24.7.3.9, “aa-logprof—Scanning the System Log”.

28 Support

  • Filename: apparmor_support.xml
  • ID: cha.apparmor.support

This chapter outlines maintenance-related tasks. Learn how to update AppArmor® and get a list of available man pages providing basic help for using the command line tools provided by AppArmor. Use the troubleshooting section to learn about some common problems encountered with AppArmor and their solutions. Report defects or enhancement requests for AppArmor following the instructions in this chapter.

28.1 Updating AppArmor Online

Updates for AppArmor packages are provided in the same way as any other update for SUSE Linux Enterprise Server. Retrieve and apply them exactly like for any other package that ships as part of SUSE Linux Enterprise Server.

28.2 Using the Man Pages

There are man pages available for your use. In a terminal, enter man apparmor to open the AppArmor man page. Man pages are distributed in sections numbered 1 through 8. Each section is specific to a category of documentation:

Table 28.1: Man Pages: Sections and Categories

Section

Category

1

User commands

2

System calls

3

Library functions

4

Device driver information

5

Configuration file formats

6

Games

7

High level concepts

8

Administrator commands

The section numbers are used to distinguish man pages from each other. For example, exit(2) describes the exit system call, while exit(3) describes the exit C library function.

The AppArmor man pages are:

  • aa-audit(8)

  • aa-autodep(8)

  • aa-complain(8)

  • aa-decode(8)

  • aa-disable(8)

  • aa-easyprof(8)

  • aa-enforce(8)

  • aa-enxec(8)

  • aa-genprof(8)

  • aa-logprof(8)

  • aa-notify(8)

  • aa-status(8)

  • aa-unconfined(8)

  • aa_change_hat(8)

  • logprof.conf(5)

  • apparmor.d(5)

  • apparmor.vim(5)

  • apparmor(7)

  • apparmor_parser(8)

  • apparmor_status(8)

28.3 For More Information

Find more information about the AppArmor product at: http://wiki.apparmor.net. Find the product documentation for AppArmor in the installed system at /usr/share/doc/manual.

There is a mailing list for AppArmor that users can post to or join to communicate with developers. See https://lists.ubuntu.com/mailman/listinfo/apparmor for details.

28.4 Troubleshooting

This section lists the most common problems and error messages that may occur using AppArmor.

28.4.1 How to React to odd Application Behavior?

If you notice odd application behavior or any other type of application problem, you should first check the reject messages in the log files to see if AppArmor is too closely constricting your application. If you detect reject messages that indicate that your application or service is too closely restricted by AppArmor, update your profile to properly handle your use case of the application. Do this with aa-logprof (Section 24.7.3.9, “aa-logprof—Scanning the System Log”).

If you decide to run your application or service without AppArmor protection, remove the application's profile from /etc/apparmor.d or move it to another location.

28.4.2 My Profiles Do not Seem to Work Anymore …

If you have been using previous versions of AppArmor and have updated your system (but kept your old set of profiles) you might notice some applications which seemed to work perfectly before you updated behaving strangely, or not working.

This version of AppArmor introduces a set of new features to the profile syntax and the AppArmor tools that might cause trouble with older versions of the AppArmor profiles. Those features are:

  • File Locking

  • Network Access Control

  • The SYS_PTRACE Capability

  • Directory Path Access

The current version of AppArmor mediates file locking and introduces a new permission mode (k) for this. Applications requesting file locking permission might misbehave or fail altogether if confined by older profiles which do not explicitly contain permissions to lock files. If you suspect this being the case, check the log file under /var/log/audit/audit.log for entries like the following:

type=AVC msg=audit(1389862802.727:13939): apparmor="DENIED" \
operation="file_lock" parent=2692 profile="/usr/bin/opera" \
name="/home/tux/.qt/.qtrc.lock" pid=28730 comm="httpd2-prefork" \
requested_mask="::k" denied_mask="::k" fsuid=30 ouid=0

Update the profile using the aa-logprof command as outlined below.

The new network access control syntax based on the network family and type specification, described in Section 21.5, “Network Access Control”, might cause application misbehavior or even stop applications from working. If you notice a network-related application behaving strangely, check the log file under /var/log/audit/audit.log for entries like the following:

type=AVC msg=audit(1389864332.233:13947): apparmor="DENIED" \
operation="socket_create" family="inet" parent=29985 profile="/bin/ping" \
sock_type="raw" pid=30251 comm="ping"

This log entry means that our example application, /bin/ping in this case, failed to get AppArmor's permission to open a network connection. This permission needs to be explicitly stated to make sure that an application has network access. To update the profile to the new syntax, use the aa-logprof command as outlined below.

The current kernel requires the SYS_PTRACE capability, if a process tries to access files in /proc/PID/fd/*. New profiles need an entry for the file and the capability, where old profiles only needed the file entry. For example:

/proc/*/fd/**  rw,

in the old syntax would translate to the following rules in the new syntax:

capability SYS_PTRACE,
/proc/*/fd/**  rw,

To update the profile to the new syntax, use the YaST Update Profile Wizard or the aa-logprof command as outlined below.

With this version of AppArmor, a few changes have been made to the profile rule syntax to better distinguish directory from file access. Therefore, some rules matching both file and directory paths in the previous version might now match a file path only. This could lead to AppArmor not being able to access a crucial directory, and thus trigger misbehavior of your application and various log messages. The following examples highlight the most important changes to the path syntax.

Using the old syntax, the following rule would allow access to files and directories in /proc/net. It would allow directory access only to read the entries in the directory, but not give access to files or directories under the directory, for example /proc/net/dir/foo would be matched by the asterisk (*), but as foo is a file or directory under dir, it cannot be accessed.

/proc/net/*  r,

To get the same behavior using the new syntax, you need two rules instead of one. The first allows access to the file under /proc/net and the second allows access to directories under /proc/net. Directory access can only be used for listing the contents, not actually accessing files or directories underneath the directory.

/proc/net/*  r,
/proc/net/*/  r,

The following rule works similarly both under the old and the new syntax, and allows access to both files and directories under /proc/net (but does not allow a directory listing of /proc/net/ itself):

/proc/net/**  r,

To distinguish file access from directory access using the above expression in the new syntax, use the following two rules. The first one only allows to recursively access directories under /proc/net while the second one explicitly allows for recursive file access only.

/proc/net/**/  r,
/proc/net/**[^/]  r,

The following rule works similarly both under the old and the new syntax and allows access to both files and directories beginning with foo under /proc/net:

/proc/net/foo**  r,

To distinguish file access from directory access in the new syntax and use the ** globbing pattern, use the following two rules. The first one would have matched both files and directories in the old syntax, but only matches files in the new syntax because of the missing trailing slash. The second rule matched neither file nor directory in the old syntax, but matches directories only in the new syntax:

/proc/net/**foo  r,
/proc/net/**foo/  r,

The following rules illustrate how the use of the ? globbing pattern has changed. In the old syntax, the first rule would have matched both files and directories (four characters, last character could be any but a slash). In the new syntax, it matches only files (trailing slash is missing). The second rule would match nothing in the old profile syntax, but matches directories only in the new syntax. The last rule matches explicitly matches a file called bar under /proc/net/foo?. Using the old syntax, this rule would have applied to both files and directories:

/proc/net/foo?  r,
/proc/net/foo?/  r,
/proc/net/foo?/bar  r,

To find and resolve issues related to syntax changes, take some time after the update to check the profiles you want to keep and proceed as follows for each application you kept the profile for:

  1. Put the application's profile into complain mode:

    aa-complain /path/to/application

    Log entries are made for any actions violating the current profile, but the profile is not enforced and the application's behavior not restricted.

  2. Run the application covering all the tasks you need this application to be able to perform.

  3. Update the profile according to the log entries made while running the application:

    aa-logprof /path/to/application
  4. Put the resulting profile back into enforce mode:

    aa-enforce /path/to/application

28.4.3 Resolving Issues with Apache

After installing additional Apache modules (like apache2-mod_apparmor) or making configuration changes to Apache, profile Apache again to find out if additional rules need to be added to the profile. If you do not profile Apache again, it could be unable to start properly or be unable to serve Web pages.

28.4.4 How to Exclude Certain Profiles from the List of Profiles Used?

Run aa-disable PROGRAMNAME to disable the profile for PROGRAMNAME. This command creates a symbolic link to the profile in /etc/apparmor.d/disable/. To reactivate the profile, delete the link, and run systemctl reload apparmor.

28.4.5 Can I Manage Profiles for Applications not Installed on my System?

Managing profiles with AppArmor requires you to have access to the log of the system on which the application is running. So you do not need to run the application on your profile build host as long as you have access to the machine that runs the application. You can run the application on one system, transfer the logs (/var/log/audit.log or, if audit is not installed, journalctl | grep -i apparmor > path_to_logfile) to your profile build host and run aa-logprof -f PATH_TO_LOGFILE.

28.4.6 How to Spot and fix AppArmor Syntax Errors?

Manually editing AppArmor profiles can introduce syntax errors. If you attempt to start or restart AppArmor with syntax errors in your profiles, error results are shown. This example shows the syntax of the entire parser error.

localhost:~ # rcapparmor start
Loading AppArmor profiles AppArmor parser error in /etc/apparmor.d/usr.sbin.squid at line 410: syntax error, unexpected TOK_ID, expecting TOK_MODE
 Profile /etc/apparmor.d/usr.sbin.squid failed to load

Using the AppArmor YaST tools, a graphical error message indicates which profile contained the error and requests you to fix it.

To fix a syntax error, log in to a terminal window as root, open the profile, and correct the syntax. Reload the profile set with systemctl reload apparmor.

Tip
Tip: AppArmor Syntax Highlighting in vi

The editor vi on SUSE Linux Enterprise Server supports syntax highlighting for AppArmor profiles. Lines containing syntax errors will be displayed with a red background.

28.5 Reporting Bugs for AppArmor

The developers of AppArmor are eager to deliver products of the highest quality. Your feedback and your bug reports help us keep the quality high. Whenever you encounter a bug in AppArmor, file a bug report against this product:

  1. Use your Web browser to go to http://bugzilla.suse.com/ and click Log In.

  2. Enter the account data of your SUSE account and click Login. If you do not have a SUSE account, click Create Account and provide the required data.

  3. If your problem has already been reported, check this bug report and add extra information to it, if necessary.

  4. If your problem has not been reported yet, select New from the top navigation bar and proceed to the Enter Bug page.

  5. Select the product against which to file the bug. In your case, this would be your product's release. Click Submit.

  6. Select the product version, component (AppArmor in this case), hardware platform, and severity.

  7. Enter a brief headline describing your problem and add a more elaborate description including log files. You may create attachments to your bug report for screenshots, log files, or test cases.

  8. Click Submit after you have entered all the details to send your report to the developers.

29 AppArmor Glossary

  • Filename: apparmor_glossary.xml
  • ID: cha.apparmor.glossary
Abstraction

See profile foundation classes below.

Apache

Apache is a freely-available Unix-based Web server. It is currently the most commonly used Web server on the Internet. Find more information about Apache at the Apache Web site at http://www.apache.org.

application fire-walling

AppArmor confines applications and limits the actions they are permitted to take. It uses privilege confinement to prevent attackers from using malicious programs on the protected server and even using trusted applications in unintended ways.

attack signature

Pattern in system or network activity that alerts of a possible virus or hacker attack. Intrusion detection systems might use attack signatures to distinguish between legitimate and potentially malicious activity.

By not relying on attack signatures, AppArmor provides "proactive" instead of "reactive" defense from attacks. This is better because there is no window of vulnerability where the attack signature must be defined for AppArmor as it does for products using attack signatures.

GUI

Graphical user interface. Refers to a software front-end meant to provide an attractive and easy-to-use interface between a computer user and application. Its elements include windows, icons, buttons, cursors, and scrollbars.

globbing

File name substitution. Instead of specifying explicit file name paths, you can use helper characters * (substitutes any number of characters except special ones such as / or ?) and ? (substitutes exactly one character) to address multiple files/directories at once. ** is a special substitution that matches any file or directory below the current directory.

HIP

Host intrusion prevention. Works with the operating system kernel to block abnormal application behavior in the expectation that the abnormal behavior represents an unknown attack. Blocks malicious packets on the host at the network level before they can hurt the application they target.

mandatory access control

A means of restricting access to objects that is based on fixed security attributes assigned to users, files, and other objects. The controls are mandatory in the sense that they cannot be modified by users or their programs.

profile

AppArmor profile completely defines what system resources an individual application can access, and with what privileges.

profile foundation classes

Profile building blocks needed for common application activities, such as DNS lookup and user authentication.

RPM

The RPM Package Manager. An open packaging system available for anyone to use. It works on Red Hat Linux, SUSE Linux Enterprise Server, and other Linux and Unix systems. It is capable of installing, uninstalling, verifying, querying, and updating computer software packages. See http://www.rpm.org/ for more information.

SSH

Secure Shell. A service that allows you to access your server from a remote computer and issue text commands through a secure connection.

streamlined access control

AppArmor provides streamlined access control for network services by specifying which files each program is allowed to read, write, and execute. This ensures that each program does what it is supposed to do and nothing else.

URI

Universal resource identifier. The generic term for all types of names and addresses that refer to objects on the World Wide Web. A URL is one kind of URI.

URL

Uniform Resource Locator. The global address of documents and other resources on the Web.

The first part of the address indicates what protocol to use and the second part specifies the IP address or the domain name where the resource is located.

For example, when you visit http://www.suse.com, you are using the HTTP protocol, as the beginning of the URL indicates.

vulnerabilities

An aspect of a system or network that leaves it open to attack. Characteristics of computer systems that allow an individual to keep it from correctly operating or that allows unauthorized users to take control of the system. Design, administrative, or implementation weaknesses or flaws in hardware, firmware, or software. If exploited, a vulnerability could lead to an unacceptable impact in the form of unauthorized access to information or the disruption of critical processing.

Part V SELinux

30 Configuring SELinux

In this chapter, you will learn how to set up and manage SELinux on SUSE Linux Enterprise Server. The following topics are covered:

30 Configuring SELinux

  • Filename: selinux.xml
  • ID: cha.selinux

In this chapter, you will learn how to set up and manage SELinux on SUSE Linux Enterprise Server. The following topics are covered:

  • Why Use SELinux?

  • Understanding SELinux

  • Setting Up SELinux

  • Managing SELinux

30.1 Why Use SELinux?

SELinux was developed as an additional Linux security solution that uses the security framework in the Linux kernel. The purpose was to allow for a more granular security policy that goes beyond what is offered by the default existing permissions of Read, Write, and Execute, and beyond assigning permissions to the different capabilities that are available on Linux. SELinux does this by trapping all system calls that reach the kernel, and denying them by default. This means that on a system that has SELinux enabled and nothing else configured, nothing will work. To allow your system to do anything, as an administrator you will need to write rules and put them in a policy.

An example explains why a solution such as SELinux (or its counterpart AppArmor) is needed:

One morning, I found out that my server was hacked. The server was running a fully patched SLES installation. A firewall was configured on it and no unnecessary services were offered by this server. Further analysis revealed that the hacker had come in through a vulnerable PHP script that was a part of one of the Apache virtual hosts that were running on this server. The intruder had managed to get access to a shell, using the wwwrun account that was used by the Apache Web server. As this wwwrun user, the intruder had created several scripts in the /var/tmp and the /tmp directories, which were a part of a botnet that was launching a Distributed Denial of Service attack against several servers.

The interesting thing about this hack is that it occurred on a server where nothing was really wrong. All permissions where set OK, but the intruder had managed to get into the system. What becomes clearly evident from this example is that in some cases additional security is needed—a security that goes beyond what is offered by using SELinux. As a less complete and less complex alternative, AppArmor can be used.

AppArmor confines specific processes in their abilities to read/write and execute files (and other things). Its view is mostly that things that happen inside a process cannot escape.

SELinux instead uses labels attached to objects (for example, files, binaries, network sockets) and uses them to determine privilege boundaries, thereby building up a level of confinement that can span more than a process or even the whole system.

SELinux was developed by the US National Security Agency (NSA), and since the beginning Red Hat has been heavily involved in its development. The first version of SELinux was offered in the era of Red Hat Enterprise Linux 4™, around the year 2006. In the beginning it offered support for essential services only, but over the years it has developed into a system that offers many rules that are collected in policies to offer protection to a broad range of services.

SELinux was developed in accordance with some certification standards like Common Criteria and FIPS 140. Because some customers specifically requested solutions that met these standards, SELinux rapidly became relatively popular.

As an alternative to SELinux, Immunix, a company that was purchased by Novell in 2005, had developed AppArmor. AppArmor was built on top of the same security principles as SELinux, but took a completely different approach, where it was possible to restrict services to exactly what they needed to do by using an easy to use wizard-driven procedure. Nevertheless, AppArmor has never reached the same status as SELinux, even if there are some good arguments to secure a server with AppArmor rather than with SELinux.

Because many organizations are requesting SELinux to be in the Linux distributions they are using, SUSE is offering support for the SELinux framework in SUSE Linux Enterprise Server. This does not mean that the default installation of SUSE Linux Enterprise Server will switch from AppArmor to SELinux in the near future.

30.1.1 Support Status

The SELinux framework is supported on SUSE Linux Enterprise Server. This means that SLES offers all binaries and libraries you need to be able to use SELinux on your server. You may however miss some software that you may be familiar with from other Linux distributions.

SELinux support is at a fairly early stage in SUSE Linux Enterprise Server, which means that unexpected behavior may occur. To limit this risk as much as possible, it is best to use only the binaries that have been provided by default on SUSE Linux Enterprise Server.

30.1.2 Understanding SELinux Components

Before starting the configuration of SELinux, you should know a bit about how SELinux is organized. Three components play a role:

  • The security framework in the Linux kernel

  • The SELinux libraries and binaries

  • The SELinux policy

The default kernel of SUSE Linux Enterprise Server supports SELinux and the tools that are needed to manage it. The most important part of the work of the administrator with regard to SELinux is managing the policy.

In the SELinux policy, security labels are applied to different objects on a Linux server. These objects typically are users, ports, processes and files. Using these security labels, rules are created that define what is and what is not allowed on a server. Remember, by default SELinux denies everything, and by creating the appropriate rules you can allow the access that is strictly necessary. Rules should therefore exist for all programs that you want to use on a system. Alternatively, you should configure parts of a system to run in unconfined mode, which means that specific ports, programs, users, files and directories are not protected by SELinux. This mode is useful if you only want to use SELinux to protect some essential services, while you are not specifically worried about other services. To get a really secure system, you should avoid this.

To ensure the appropriate protection of your system, you need an SELinux policy. This must be a tailor-made policy in which all files are provided with a label, and all services and users have a security label as well to express which files and directories can be accessed by which user and processed on the server. Developing such a policy is a tremendous amount of work.

The complexity of SELinux is also one of the main arguments against using it. Because a typical Linux system is so very complex, it is easy to overlook something and leave an opening that intruders can abuse to get into your system. And even if it is set up completely the way it should be, it still is very hard for an administrator to overlook all aspects with SELinux. With regard to the complexity, AppArmor takes a completely different approach and works with automated procedures that allow the administrator to set up AppArmor protection and understand exactly what is happening.

Note that a freely available SELinux policy might work on your server, but is unlikely to offer the same protection as a custom policy. SUSE also does not support third-party policies.

30.2 Policy

As mentioned, the policy is the key component in SELinux. It defines rules that specify which objects can access which files, directories, ports and processes on a system. To do this, a security context is defined for all of these. On an SELinux system where the policy has been applied to label the file system, you can use the ls -Z command on any directory to find the security context for the files in that directory. Example 30.1: “Security Context Settings Using ls -Z shows the security context settings for the directories in the / directory of a SUSE Linux Enterprise Server system with an SELinux-labeled file system.

Example 30.1: Security Context Settings Using ls -Z
ls -Z
system_u:object_r:bin_t bin
system_u:object_r:boot_t boot
system_u:object_r:device_t dev
system_u:object_r:etc_t etc
system_u:object_r:home_root_t home
system_u:object_r:lib_t lib
system_u:object_r:lib_t lib64
system_u:object_r:lost_found_t lost+found
system_u:object_r:mnt_t media
system_u:object_r:mnt_t mnt
system_u:object_r:usr_t opt
system_u:object_r:proc_t proc
system_u:object_r:default_t root
system_u:object_r:bin_t sbin
system_u:object_r:security_t selinux
system_u:object_r:var_t srv
system_u:object_r:sysfs_t sys
system_u:object_r:tmp_t tmp
system_u:object_r:usr_t usr
system_u:object_r:var_t var

The most important line in the security context is the context type. This is the part of the security context that ends in _t. It tells SELinux which kind of access the object is allowed. In the policy, rules are specified to define which type of user or which type of role has access to which type of context. For example, this can happen by using a rule like the following:

allow user_t bin_t:file {read execute gettattr};

This example rule states that the user who has the context type user_t (this user is called the source object) is allowed to access objects of class "file" with the context type bin_t (the target), using the permissions read, execute and getattr.

The standard policy that you are going to use contains a huge amount of rules. To make it more manageable, policies are often split into modules. This allows administrator to switch protection on or off for different parts of the system.

When compiling the policy for your system, you will have a choice to either work with a modular policy, or a monolithic policy, where one huge policy is used to protect everything on your system. It is strongly recommended to use a modular policy and not a monolithic policy. Modular policies are much easier to manage.

30.3 Installing SELinux Packages and Modifying GRUB 2

The easiest way to make sure that all SELinux components are installed is by using YaST. The procedure described below shows what to do on an installed SUSE Linux Enterprise Server:

  1. Log in to your server as root and start YaST.

  2. Select Software › Software Management

  3. Select View › Patterns and select the entire C/C++ Development category for installation.

  4. Select View › Search and make sure that Search in Name, Keywords and Summary are selected. Now enter the keyword selinux and click Search. You now see a list of packages.

  5. Make sure that all the packages you have found are selected and click Accept to install them.

Selecting all SELinux Packages in YaST
Figure 30.1: Selecting all SELinux Packages in YaST

After installing the SELinux packages, you need to modify the GRUB 2 boot loader. Do this from YaST, select System › Boot Loader › Kernel Parameters. Now add the following parameters to the Optional Kernel Command Line Parameters:

security=selinux selinux=1 enforcing=0

These options are used for the following purposes:

security=selinux

This option tells the kernel to use SELinux and not AppArmor

selinux=1

This option switches on SELinux

enforcing=0

This option puts SELinux in permissive mode. In this mode, SELinux is fully functional, but does not enforce any of the security settings in the policy. Use this mode for configuring your system. To switch on SELinux protection, when the system is fully operational, change the option to enforcing=1 and add SELINUX=enforcing in /etc/selinux/config.

After installing the SELinux packages and enabling the SELinux GRUB 2 boot options, reboot your server to activate the configuration.

30.4 SELinux Policy

The policy is an essential component of SELinux. SUSE Linux Enterprise Server 12 SP3 includes the minimum SELinux reference policy in the package selinux-policy-minimum. The examples in this chapter refer to this policy if not stated otherwise.

Tip
Tip

To install a different policy, you need to download it from https://build.opensuse.org/package/binaries/security:SELinux/selinux-policy?repository=SLE_12 and install:

sudo zypper in selinux-policy-targeted-VERSION_NUMBER.noarch.rpm

After installing the policy, you are ready to start file system labeling. Run

restorecon -Rp /

to start the /sbin/setfiles command to label all files on your system. The /etc/selinux/minimum/contexts/files/file_contexts input file is used. The file_contexts file needs to match your actual file system as much as possible. Otherwise, it can lead to a completely unbootable system. If that happens, modify the records in file_contexts with the semanage fcontext command to match the real structure of the file system your server is using. For example

semanage fcontext -a -t samba_share_t /etc/example_file

changes the file type from the default etc_t to samba_share_t and adds the following record to the related file_contexts.local file:

/etc/example_file    unconfined_u:object_r:samba_share_t:s0

Then run

restorecon -v /etc/example_file

for the type change to take effect.

Before doing this, make sure to read the rest of this chapter, so you fully understand how context type is applied to files and directories. Do not forget to make a backup of the file_contexts file before starting.

Note
Note: The User nobody

While using semanage, you may get a message that complains about the home directory of nobody. In this case, change the login shell of user nobody to /sbin/nologin. Then the settings of nobody match the current policy settings.

After another reboot SELinux should be operational. To verify this, use the command sestatus -v. It should give you an output similar to Example 30.2: “Verifying that SELinux is functional”.

Example 30.2: Verifying that SELinux is functional
sestatus -v
SELinux status:                 enabled
SELinuxfs mount:                /selinux
Current mode:                   permissive
Mode from config file:          permissive
Policy version:                 26
Policy from config file:        minimum

Process contexts:
Current context:                root:staff_r:staff_t
Init context:                   system_u:system_r:init_t
/sbin/mingetty                  system_u:system_r:sysadm_t
/usr/sbin/sshd                  system_u:system_r:sshd_t

File contexts:
Controlling term:               root:object_r:user_devpts_t
/etc/passwd                     system_u:object_r:etc_t
/etc/shadow                     system_u:object_r:shadow_t
/bin/bash                       system_u:object_r:shell_exec_t
/bin/login                      system_u:object_r:login_exec_t
/bin/sh                         system_u:object_r:bin_t -> system_u:object_r:shell_exec_t
/sbin/agetty                    system_u:object_r:getty_exec_t
/sbin/init                      system_u:object_r:init_exec_t
/sbin/mingetty                  system_u:object_r:getty_exec_t
/usr/sbin/sshd                  system_u:object_r:sshd_exec_t
/lib/libc.so.6                  system_u:object_r:lib_t -> system_u:object_r:lib_t
/lib/ld-linux.so.2              system_u:object_r:lib_t -> system_u:object_r:ld_so_t

30.5 Configuring SELinux

At this point you have a completely functional SELinux system and it is time to further configure it. In the current status, SELinux is operational but not in enforcing mode. This means that it does not limit you in doing anything, it logs everything that it should be doing if it were in enforcing mode. This is good, because based on the log files you can find what it is that it would prevent you from doing. As a first test, put SELinux in enforcing mode and find out if you can still use your server after doing so: check that the option enforcing=1 is set in the GRUB 2 configuration file, while SELINUX=enforcing is set in /etc/selinux/config. Reboot your server and see if it still comes up the way you expect it to. If it does, leave it like that and start modifying the server in a way that everything works as expected. However, you may not even be able to boot the server properly. In that case, switch back to the mode where SELinux is not enforcing and start tuning your server.

Before you start tuning your server, verify the SELinux installation. You have already used the command sestatus -v to view the current mode, process, and file contexts. Next, run

semanage boolean -l

which lists all Boolean switches that are available, and at the same time verifies that you can access the policy. Example 30.3, “Getting a List of Booleans and Verifying Policy Access” shows part of the output of this command.

Example 30.3: Getting a List of Booleans and Verifying Policy Access
semanage boolean -l
SELinux boolean                          Description
ftp_home_dir                   -> off   ftp_home_dir
mozilla_read_content           -> off   mozilla_read_content
spamassassin_can_network       -> off   spamassassin_can_network
httpd_can_network_relay        -> off   httpd_can_network_relay
openvpn_enable_homedirs        -> off   openvpn_enable_homedirs
gpg_agent_env_file             -> off   gpg_agent_env_file
allow_httpd_awstats_script_anon_write -> off   allow_httpd_awstats_script_anon_write
httpd_can_network_connect_db   -> off   httpd_can_network_connect_db
allow_ftpd_full_access         -> off   allow_ftpd_full_access
samba_domain_controller        -> off   samba_domain_controller
httpd_enable_cgi               -> off   httpd_enable_cgi
virt_use_nfs                   -> off   virt_use_nfs

Another command that outputs useful information at this stage is

semanage fcontext -l

It shows the default file context settings as provided by the policy (see Example 30.4: “Getting File Context Information” for partial output of this command).

Example 30.4: Getting File Context Information
semanage fcontext -l
/var/run/usb(/.*)?                                 all files          system_u:object_r:hotplug_var_run_t
/var/run/utmp                                      regular file       system_u:object_r:initrc_var_run_t
/var/run/vbe.*                                     regular file       system_u:object_r:hald_var_run_t
/var/run/vmnat.*                                   socket             system_u:object_r:vmware_var_run_t
/var/run/vmware.*                                  all files          system_u:object_r:vmware_var_run_t
/var/run/vpnc(/.*)?                                all files          system_u:object_r:vpnc_var_run_t
/var/run/watchdog\.pid                             regular file       system_u:object_r:watchdog_var_run_t
/var/run/winbindd(/.*)?                            all files          system_u:object_r:winbind_var_run_t
/var/run/wnn-unix(/.*)                             all files          system_u:object_r:canna_var_run_t
/var/run/wpa_supplicant(/.*)?                      all files          system_u:object_r:NetworkManager_var_run_t
/var/run/wpa_supplicant-global                     socket             system_u:object_r:NetworkManager_var_run_t
/var/run/xdmctl(/.*)?                              all files          system_u:object_r:xdm_var_run_t
/var/run/yiff-[0-9]+\.pid                          regular file       system_u:object_r:soundd_var_run_t

30.6 Managing SELinux

The base SELinux configuration is now operational and it can now be configured to secure your server. In SELinux, an additional set of rules is used to define exactly which process or user can access which files, directories, or ports. To do this, SELinux applies a context to every file, directory, process, and port. This context is a security label that defines how this file, directory, process, or port should be treated. These context labels are used by the SELinux policy, which defines exactly what should be done with the context labels. By default, the policy blocks all non-default access, which means that, as an administrator, you need to enable all features that are non-default on your server.

30.6.1 Viewing the Security Context

As already mentioned, files, directories, and ports can be labeled. Within each label, different contexts are used. To be able to perform your daily administration work, the type context is what you are most interested in. As an administrator, you will mostly work with the type context. Many commands allow you to use the -Z option to list current context settings. In Example 30.5: “The default context for directories in the root directory” you can see what the context settings are for the directories in the root directory.

Example 30.5: The default context for directories in the root directory
ls -Z
dr-xr-xr-x. root root system_u:object_r:bin_t:s0       bin
dr-xr-xr-x. root root system_u:object_r:boot_t:s0      boot
drwxr-xr-x. root root system_u:object_r:cgroup_t:s0    cgroup
drwxr-xr-x+ root root unconfined_u:object_r:default_t:s0 data
drwxr-xr-x. root root system_u:object_r:device_t:s0    dev
drwxr-xr-x. root root system_u:object_r:etc_t:s0       etc
drwxr-xr-x. root root system_u:object_r:home_root_t:s0 home
dr-xr-xr-x. root root system_u:object_r:lib_t:s0       lib
dr-xr-xr-x. root root system_u:object_r:lib_t:s0       lib64
drwx------. root root system_u:object_r:lost_found_t:s0 lost+found
drwxr-xr-x. root root system_u:object_r:mnt_t:s0       media
drwxr-xr-x. root root system_u:object_r:autofs_t:s0    misc
drwxr-xr-x. root root system_u:object_r:mnt_t:s0       mnt
drwxr-xr-x. root root unconfined_u:object_r:default_t:s0 mnt2
drwxr-xr-x. root root unconfined_u:object_r:default_t:s0 mounts
drwxr-xr-x. root root system_u:object_r:autofs_t:s0    net
drwxr-xr-x. root root system_u:object_r:usr_t:s0       opt
dr-xr-xr-x. root root system_u:object_r:proc_t:s0      proc
drwxr-xr-x. root root unconfined_u:object_r:default_t:s0 repo
dr-xr-x---. root root system_u:object_r:admin_home_t:s0 root
dr-xr-xr-x. root root system_u:object_r:bin_t:s0       sbin
drwxr-xr-x. root root system_u:object_r:security_t:s0  selinux
drwxr-xr-x. root root system_u:object_r:var_t:s0       srv
-rw-r--r--. root root unconfined_u:object_r:swapfile_t:s0 swapfile
drwxr-xr-x. root root system_u:object_r:sysfs_t:s0     sys
drwxrwxrwt. root root system_u:object_r:tmp_t:s0       tmp
-rw-r--r--. root root unconfined_u:object_r:etc_runtime_t:s0 tmp2.tar
-rw-r--r--. root root unconfined_u:object_r:etc_runtime_t:s0 tmp.tar
drwxr-xr-x. root root system_u:object_r:usr_t:s0       usr
drwxr-xr-x. root root system_u:object_r:var_t:s0       var

In the listing above, you can see the complete context for all directories. It consists of a user, a role, and a type. The s0 setting indicates the security level in Multi Level Security environments. These environments are not discussed here. In such an environment, make sure that s0 is set. The Context Type defines what kind of activity is permitted in the directory. Compare, for example, the /root directory, which has the admin_home_t context type, and the /home directory, which has the home_root_t context type. In the SELinux policy, different kinds of access are defined for these context types.

Security labels are not only associated with files, but also with other items, such as ports and processes. In Example 30.6: “Showing SELinux settings for processes with ps Zaux for example you can see the context settings for processes on your server.

Example 30.6: Showing SELinux settings for processes with ps Zaux
ps Zaux
LABEL                           USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
system_u:system_r:init_t        root         1  0.0  0.0  10640   808 ?        Ss   05:31   0:00 init [5]
system_u:system_r:kernel_t      root         2  0.0  0.0      0     0 ?        S    05:31   0:00 [kthreadd]
system_u:system_r:kernel_t      root         3  0.0  0.0      0     0 ?        S    05:31   0:00 [ksoftirqd/0]
system_u:system_r:kernel_t      root         6  0.0  0.0      0     0 ?        S    05:31   0:00 [migration/0]
system_u:system_r:kernel_t      root         7  0.0  0.0      0     0 ?        S    05:31   0:00 [watchdog/0]
system_u:system_r:sysadm_t      root      2344  0.0  0.0  27640   852 ?        Ss   05:32   0:00 /usr/sbin/mcelog --daemon --config-file /etc/mcelog/mcelog.conf
system_u:system_r:sshd_t        root      3245  0.0  0.0  69300  1492 ?        Ss   05:32   0:00 /usr/sbin/sshd -o PidFile=/var/run/sshd.init.pid
system_u:system_r:cupsd_t       root      3265  0.0  0.0  68176  2852 ?        Ss   05:32   0:00 /usr/sbin/cupsd
system_u:system_r:nscd_t        root      3267  0.0  0.0 772876  1380 ?        Ssl  05:32   0:00 /usr/sbin/nscd
system_u:system_r:postfix_master_t root   3334  0.0  0.0  38320  2424 ?        Ss   05:32   0:00 /usr/lib/postfix/master
system_u:system_r:postfix_qmgr_t postfix  3358  0.0  0.0  40216  2252 ?        S    05:32   0:00 qmgr -l -t fifo -u
system_u:system_r:crond_t       root      3415  0.0  0.0  14900   800 ?        Ss   05:32   0:00 /usr/sbin/cron
system_u:system_r:fsdaemon_t    root      3437  0.0  0.0  16468  1040 ?        S    05:32   0:00 /usr/sbin/smartd
system_u:system_r:sysadm_t      root      3441  0.0  0.0  66916  2152 ?        Ss   05:32   0:00 login -- root
system_u:system_r:sysadm_t      root      3442  0.0  0.0   4596   800 tty2     Ss+  05:32   0:00 /sbin/mingetty tty2

30.6.2 Selecting the SELinux Mode

In SELinux, three different modes can be used:

Enforcing:

This is the default mode. SELinux protects your server according to the rules in the policy, and SELinux logs all of its activity to the audit log.

Permissive:

This mode is useful for troubleshooting. If set to Permissive, SELinux does not protect your server, but it still logs everything that happens to the log files.

Disabled:

In this mode, SELinux is switched off completely and no logging occurs. The file system labels however are not removed from the file system.

You have already read how you can set the current SELinux mode from GRUB 2 while booting using the enforcing boot parameter.

30.6.3 Modifying SELinux Context Types

An important part of the work of an administrator is setting context types on files to ensure appropriate working of SELinux.

If a file is created within a specific directory, it inherits the context type of the parent directory by default. If, however, a file is moved from one location to another location, it retains the context type that it had in the old location.

To set the context type for files, you can use the semanage fcontext command. With this command, you write the new context type to the policy, but it does not change the actual context type immediately! To apply the context types that are in the policy, you need to run the restorecon command afterward.

The challenge when working with semanage fcontext is to find out which context you actually need. You can use

semanage fcontext -l

to list all contexts in the policy, but it may be a bit hard to find out the actual context you need from that list as it is rather long (see Example 30.7: “Viewing Default File Contexts”).

Example 30.7: Viewing Default File Contexts
semanage fcontext -l | less
SELinux fcontext                                   type               Context

/                                                  directory          system_u:object_r:root_t:s0
/.*                                                all files          system_u:object_r:default_t:s0
/[^/]+                                             regular file       system_u:object_r:etc_runtime_t:s0
/\.autofsck                                        regular file       system_u:object_r:etc_runtime_t:s0
/\.autorelabel                                     regular file       system_u:object_r:etc_runtime_t:s0
/\.journal                                         all files          X:>>None>>
/\.suspended                                       regular file       system_u:object_r:etc_runtime_t:s0
/a?quota\.(user|group)                             regular file       system_u:object_r:quota_db_t:s0
/afs                                               directory          system_u:object_r:mnt_t:s0
/bin                                               directory          system_u:object_r:bin_t:s0
/bin/.*                                            all files          system_u:object_r:bin_t:s0

There are three ways to find out which context settings are available for your services:

  • Install the service and look at the default context settings that are used. This is the easiest and recommended option.

  • Consult the man page for the specific service. Some services have a man page that ends in _selinux, which contains all the information you need to find the correct context settings.

    When you have found the right context setting, apply it using semanage fcontext. This command takes -t context type as its first argument, followed by the name of the directory or file to which you want to apply the context settings. To apply the context to everything that already exists in the directory where you want to apply the context, you add the regular expression (/.*)? to the name of the directory. This means: optionally, match a slash followed by any character. The examples section of the semanage man page has some useful usage examples for semanage. For more information on regular expressions, see for example the tutorial at http://www.regular-expressions.info/.

  • Display a list of all context types that are available on your system:

    seinfo -t

    Since the command by itself outputs an overwhelming amount of information, it should be used in combination with grep or a similar command for filtering.

30.6.4 Applying File Contexts

To help you apply the SELinux context properly, the following procedure shows how to set a context using semanage fcontext and restorecon. You will notice that at first attempt, the Web server with a non-default document root does not work. After changing the SELinux context, it will:

  1. Create the /web directory and then change to it:

    sudo mkdir /web  && cd /web
  2. Use a text editor to create the file /web/index.html that contains the text welcome to my Web site.

  3. Open the file /etc/apache2/default-server.conf with an editor, and change the DocumentRoot line to DocumentRoot /web

  4. Start the Apache Web server:

    sudo systemctl start apache2
  5. Open a session to your local Web server:

    w3m localhost

    You will receive a Connection refused message. Press Enter, and then q to quit w3m.

  6. Find the current context type for the default Apache DocumentRoot, which is /srv/www/htdocs. It should be set to httpd_sys_content_t:

    ls -Z /srv/www
  7. Set the new context in the policy and press Enter:

    semanage fcontext -a -f "" -t httpd_sys_content_t '/web(/.*) ?'
  8. Apply the new context type:

    restorecon /web
  9. Show the context of the files in the directory /web. You will see that the new context type has been set properly to the /web directory, but not to its contents.

    ls -Z /web
  10. Apply the new context recursively to the /web directory. The type context has now been set correctly.

    restorecon -R /web
  11. Restart the Web server:

    sudo systemctl restart apache2

    You should now be able to access the contents of the /web directory.

30.6.5 Configuring SELinux Policies

The easiest way to change the behavior of the policy is by working with Booleans. These are on-off switches that you can use to change the settings in the policy. To find out which Booleans are available, run

semanage boolean -l

It will show a long list of Booleans, with a short description of what each of these Booleans will do for you. When you have found the Boolean you want to set, you can use setsebool -P, followed by the name of the Boolean that you want to change. It is important to use the -P option at all times when using setsebool. This option writes the setting to the policy file on disk, and this is the only way to make sure that the Boolean is applied automatically after a reboot.

The procedure below gives an example of changing Boolean settings

  1. List Booleans that are related to FTP servers.

    semanage boolean -l | grep ftp
  2. Turn the Boolean off:

    setsebool allow_ftpd_anon_write off

    Note that it does not take much time to write the change. Then verify that the Boolean is indeed turned off:

    semanage boolean -l|grep ftpd_anon
  3. Reboot your server.

  4. Check again to see if the allow_ftpd_anon_write Boolean is still turned on. As it has not yet been written to the policy, you will notice that it is off.

  5. Switch the Boolean and write the setting to the policy:

    setsebool -P allow_ftpd_anon_write

30.6.6 Working with SELinux Modules

By default, SELinux uses a modular policy. This means that the policy that implements SELinux features is not just one huge policy, but it consists of many smaller modules. Each module covers a specific part of the SELinux configuration. The concept of the SELinux module was introduced to make it easier for third party vendors to make their services compatible with SELinux. To get an overview of the SELinux modules, you can use the semodule -l command. This command lists all current modules in use by SELinux and their version numbers.

As an administrator, you can switch modules on or off. This can be useful if you want to disable only a part of SELinux and not everything to run a specific service without SELinux protection. Especially in the case of SUSE Linux Enterprise Server, where there is not a completely supported SELinux policy yet, it can make sense to switch off all modules that you do not need so that you can focus on the services that really do need SELinux protection. To switch off an SELinux module, use

semodule -d MODULENAME

To switch it on again, you can use

semodule -e modulename

As an administrator, you do not typically change the contents of the policy files that come from the SELinux Policy RPM. You would rather use semanage fcontext to change file contexts. If you are using audit2allow to generate policies for your server, you should change the policy files after all.

To change the contents of any of the policy module files, compile the changes into a new policy module file. To do this, first install the selinux-policy-devel package. Then, in the directory where the files created by audit2allow are located, run:

make -f /usr/share/selinux/devel/Makefile

When make has completed, you can manually load the modules into the system, using semodule -i.

30.7 Troubleshooting

By default, if SELinux is the reason something is not working, a log message to this effect is sent to the /var/log/audit/audit.log file. That is, if the auditd service is running. If you see an empty /var/log/audit, start the auditd service using

sudo systemctl start auditd

and enable it in the targets of your system, using

sudo systemctl enable auditd

In Example 30.8: “Example Lines from /etc/audit/audit.log you can see a partial example of the contents of /var/log/audit/audit.log

Example 30.8: Example Lines from /etc/audit/audit.log
type=DAEMON_START msg=audit(1348173810.874:6248): auditd start, ver=1.7.7 format=raw kernel=3.0.13-0.27-default auid=0 pid=4235 subj=system_u:system_r:auditd_t res=success
type=AVC msg=audit(1348173901.081:292): avc:  denied  { write } for  pid=3426 comm="smartd" name="smartmontools" dev=sda6 ino=581743 scontext=system_u:system_r:fsdaemon_t tcontext=system_u:object_r:var_lib_t tclass=dir
type=AVC msg=audit(1348173901.081:293): avc:  denied  { remove_name } for  pid=3426 comm="smartd" name="smartd.WDC_WD2500BEKT_75PVMT0-WD_WXC1A21E0454.ata.state~" dev=sda6 ino=582390 scontext=system_u:system_r:fsdaemon_t tcontext=system_u:object_r:var_lib_t tclass=dir
type=AVC msg=audit(1348173901.081:294): avc:  denied  { unlink } for  pid=3426 comm="smartd" name="smartd.WDC_WD2500BEKT_75PVMT0-WD_WXC1A21E0454.ata.state~" dev=sda6 ino=582390 scontext=system_u:system_r:fsdaemon_t tcontext=system_u:object_r:var_lib_t tclass=file
type=AVC msg=audit(1348173901.081:295): avc:  denied  { rename } for  pid=3426 comm="smartd" name="smartd.WDC_WD2500BEKT_75PVMT0-WD_WXC1A21E0454.ata.state" dev=sda6 ino=582373 scontext=system_u:system_r:fsdaemon_t tcontext=system_u:object_r:var_lib_t tclass=file
type=AVC msg=audit(1348173901.081:296): avc:  denied  { add_name } for  pid=3426 comm="smartd" name="smartd.WDC_WD2500BEKT_75PVMT0-WD_WXC1A21E0454.ata.state~" scontext=system_u:system_r:fsdaemon_t tcontext=system_u:object_r:var_lib_t tclass=dir
type=AVC msg=audit(1348173901.081:297): avc:  denied  { create } for  pid=3426 comm="smartd" name="smartd.WDC_WD2500BEKT_75PVMT0-WD_WXC1A21E0454.ata.state" scontext=system_u:system_r:fsdaemon_t tcontext=system_u:object_r:var_lib_t tclass=file
type=AVC msg=audit(1348173901.081:298): avc:  denied  { write open } for  pid=3426 comm="smartd" name="smartd.WDC_WD2500BEKT_75PVMT0-WD_WXC1A21E0454.ata.state" dev=sda6 ino=582390 scontext=system_u:system_r:fsdaemon_t tcontext=system_u:object_r:var_lib_t tclass=file
type=AVC msg=audit(1348173901.081:299): avc:  denied  { getattr } for  pid=3426 comm="smartd" path="/var/lib/smartmontools/smartd.WDC_WD2500BEKT_75PVMT0-WD_WXC1A21E0454.ata.state" dev=sda6 ino=582390 scontext=system_u:system_r:fsdaemon_t tcontext=system_u:object_r:var_lib_t tclass=file
type=AVC msg=audit(1348173901.309:300): avc:  denied  { append } for  pid=1316

At first look, the lines in audit.log are a bit hard to read. However, on closer examination they are not that hard to understand. Every line can be broken down into sections. For example, the sections in the last line are:

type=AVC:

every SELinux-related audit log line starts with the type identification type=AVC

msg=audit(1348173901.309:300):

This is the time stamp, which unfortunately is written in epoch time, the number of seconds that have passed since Jan 1, 1970. You can use date -d on the part up to the dot in the epoch time notation to find out when the event has happened:

date -d @1348173901
Thu Sep 20 16:45:01 EDT 2012
avc: denied { append }:

the specific action that was denied. In this case the system has denied the appending of data to a file. While browsing through the audit log file, you can see other system actions, such as write open, getattr and more.

for pid=1316:

the process ID of the command or process that initiated the action

comm="rsyslogd":

the specific command that was associated with that PID

name="smartmontools":

the name of the subject of the action

dev=sda6 ino=582296:

the block device and inode number of the file that was involved

scontext=system_u:system_r:syslogd_t:

the source context, which is the context of the initiator of the action

tclass=file:

a class identification of the subject

Instead of interpreting the events in audit.log yourself, there is another approach. You can use the audit2allow command, which helps analyze the cryptic log messages in /var/log/audit/audit.log. An audit2allow troubleshooting session always consists of three different commands. First, you would use audit2allow -w -a to present the audit information in a more readable way. The audit2allow -w -a by default works on the audit.log file. If you want to analyze a specific message in the audit.log file, copy it to a temporary file and analyze the file with:

audit2allow -w -i FILENAME
Example 30.9: Analyzing Audit Messages
audit2allow -w -i testfile
type=AVC msg=audit(1348173901.309:300): avc:  denied  { append } for  pid=1316
comm="rsyslogd" name="acpid" dev=sda6 ino=582296
scontext=system_u:system_r:syslogd_t tcontext=system_u:object_r:apmd_log_t tclass=file
This was caused by:

Missing type enforcement (TE) allow rule.

To generate a loadable module to allow this access, run

audit2allow

To find out which specific rule has denied access, you can use audit2allow -a to show the enforcing rules from all events that were logged to the audit.log file, or audit2allow -i FILENAME to show it for messages that you have stored in a specific file:

Example 30.10: Viewing Which Lines Deny Access
audit2allow -i testfile
#============= syslogd_t ==============
allow syslogd_t apmd_log_t:file append;

To create an SELinux module with the name mymodule that you can load to allow the access that was previously denied, run

audit2allow -a -R -M mymodule

If you want to do this for all events that have been logged to the audit.log, use the -a -M command arguments. To do it only for specific messages that are in a specific file, use -i -M as in the example below:

Example 30.11: Creating a Policy Module Allowing an Action Previously Denied
audit2allow -i testfile -M example
******************** IMPORTANT ***********************
To make this policy package active, execute:

semodule -i example.pp

As indicated by the audit2allow command, you can now run this module by using the semodule -i command, followed by the name of the module that audit2allow has created for you (example.pp in the above example).

Part VI The Linux Audit Framework

31 Understanding Linux Audit

The Linux audit framework as shipped with this version of SUSE Linux Enterprise Server provides a CAPP-compliant (Controlled Access Protection Profiles) auditing system that reliably collects information about any security-relevant event. The audit records can be examined to determine whether any violation of the security policies has been committed, and by whom.

Providing an audit framework is an important requirement for a CC-CAPP/EAL (Common Criteria-Controlled Access Protection Profiles/Evaluation Assurance Level) certification. Common Criteria (CC) for Information Technology Security Information is an international standard for independent security evaluations. Common Criteria helps customers judge the security level of any IT product they intend to deploy in mission-critical setups.

Common Criteria security evaluations have two sets of evaluation requirements, functional and assurance requirements. Functional requirements describe the security attributes of the product under evaluation and are summarized under the Controlled Access Protection Profiles (CAPP). Assurance requirements are summarized under the Evaluation Assurance Level (EAL). EAL describes any activities that must take place for the evaluators to be confident that security attributes are present, effective, and implemented. Examples for activities of this kind include documenting the developers' search for security vulnerabilities, the patch process, and testing.

This guide provides a basic understanding of how audit works and how it can be set up. For more information about Common Criteria itself, refer to the Common Criteria Web site.

32 Setting Up the Linux Audit Framework

This chapter shows how to set up a simple audit scenario. Every step involved in configuring and enabling audit is explained in detail. After you have learned to set up audit, consider a real-world example scenario in Chapter 33, Introducing an Audit Rule Set.

33 Introducing an Audit Rule Set

The following example configuration illustrates how audit can be used to monitor your system. It highlights the most important items that need to be audited to cover the list of auditable events specified by Controlled Access Protection Profile (CAPP).

34 Useful Resources

There are other resources available containing valuable information about the Linux audit framework:

31 Understanding Linux Audit

  • Filename: audit_components.xml
  • ID: cha.audit.comp
Abstract

The Linux audit framework as shipped with this version of SUSE Linux Enterprise Server provides a CAPP-compliant (Controlled Access Protection Profiles) auditing system that reliably collects information about any security-relevant event. The audit records can be examined to determine whether any violation of the security policies has been committed, and by whom.

Providing an audit framework is an important requirement for a CC-CAPP/EAL (Common Criteria-Controlled Access Protection Profiles/Evaluation Assurance Level) certification. Common Criteria (CC) for Information Technology Security Information is an international standard for independent security evaluations. Common Criteria helps customers judge the security level of any IT product they intend to deploy in mission-critical setups.

Common Criteria security evaluations have two sets of evaluation requirements, functional and assurance requirements. Functional requirements describe the security attributes of the product under evaluation and are summarized under the Controlled Access Protection Profiles (CAPP). Assurance requirements are summarized under the Evaluation Assurance Level (EAL). EAL describes any activities that must take place for the evaluators to be confident that security attributes are present, effective, and implemented. Examples for activities of this kind include documenting the developers' search for security vulnerabilities, the patch process, and testing.

This guide provides a basic understanding of how audit works and how it can be set up. For more information about Common Criteria itself, refer to the Common Criteria Web site.

Linux audit helps make your system more secure by providing you with a means to analyze what is happening on your system in great detail. It does not, however, provide additional security itself—it does not protect your system from code malfunctions or any kind of exploits. Instead, audit is useful for tracking these issues and helps you take additional security measures, like AppArmor, to prevent them.

Audit consists of several components, each contributing crucial functionality to the overall framework. The audit kernel module intercepts the system calls and records the relevant events. The auditd daemon writes the audit reports to disk. Various command line utilities take care of displaying, querying, and archiving the audit trail.

Audit enables you to do the following:

Associate Users with Processes

Audit maps processes to the user ID that started them. This makes it possible for the administrator or security officer to exactly trace which user owns which process and is potentially doing malicious operations on the system.

Important
Important: Renaming User IDs

Audit does not handle the renaming of UIDs. Therefore avoid renaming UIDs (for example, changing tux from uid=1001 to uid=2000) and obsolete UIDs rather than renaming them. Otherwise you would need to change auditctl data (audit rules) and would have problems retrieving old data correctly.

Review the Audit Trail

Linux audit provides tools that write the audit reports to disk and translate them into human readable format.

Review Particular Audit Events

Audit provides a utility that allows you to filter the audit reports for certain events of interest. You can filter for:

  • User

  • Group

  • Audit ID

  • Remote Host Name

  • Remote Host Address

  • System Call

  • System Call Arguments

  • File

  • File Operations

  • Success or Failure

Apply a Selective Audit

Audit provides the means to filter the audit reports for events of interest and to tune audit to record only selected events. You can create your own set of rules and have the audit daemon record only those of interest to you.

Guarantee the Availability of the Report Data

Audit reports are owned by root and therefore only removable by root. Unauthorized users cannot remove the audit logs.

Prevent Audit Data Loss

If the kernel runs out of memory, the audit daemon's backlog is exceeded, or its rate limit is exceeded, audit can trigger a shutdown of the system to keep events from escaping audit's control. This shutdown would be an immediate halt of the system triggered by the audit kernel component without synchronizing the latest logs to disk. The default configuration is to log a warning to syslog rather than to halt the system.

If the system runs out of disk space when logging, the audit system can be configured to perform clean shutdown. The default configuration tells the audit daemon to stop logging when it runs out of disk space.

31.1 Introducing the Components of Linux Audit

The following figure illustrates how the various components of audit interact with each other:

Introducing the Components of Linux Audit
Figure 31.1: Introducing the Components of Linux Audit

Straight arrows represent the data flow between components while dashed arrows represent lines of control between components.

auditd

The audit daemon is responsible for writing the audit messages that were generated through the audit kernel interface and triggered by application and system activity to disk. The way the audit daemon is started is controlled by systemd. The audit system functions (when started) are controlled by /etc/audit/auditd.conf. For more information about auditd and its configuration, refer to Section 31.2, “Configuring the Audit Daemon”.

auditctl

The auditctl utility controls the audit system. It controls the log generation parameters and kernel settings of the audit interface and the rule sets that determine which events are tracked. For more information about auditctl, refer to Section 31.3, “Controlling the Audit System Using auditctl.

audit rules

The file /etc/audit/audit.rules contains a sequence of auditctl commands that are loaded at system boot time immediately after the audit daemon is started. For more information about audit rules, refer to Section 31.4, “Passing Parameters to the Audit System”.

aureport

The aureport utility allows you to create custom reports from the audit event log. This report generation can easily be scripted, and the output can be used by various other applications, for example, to plot these results. For more information about aureport, refer to Section 31.5, “Understanding the Audit Logs and Generating Reports”.

ausearch

The ausearch utility can search the audit log file for certain events using various keys or other characteristics of the logged format. For more information about ausearch, refer to Section 31.6, “Querying the Audit Daemon Logs with ausearch.

audispd

The audit dispatcher daemon (audispd) can be used to relay event notifications to other applications instead of (or in addition to) writing them to disk in the audit log. For more information about audispd, refer to Section 31.9, “Relaying Audit Event Notifications”.

autrace

The autrace utility traces individual processes in a fashion similar to strace. The output of autrace is logged to the audit log. For more information about autrace, refer to Section 31.7, “Analyzing Processes with autrace.

aulast

Prints a list of the last logged-in users, similarly to last. aulast searches back through the audit logs (or the given audit log file) and displays a list of all users logged in and out based on the range of time in the audit logs.

aulastlog

Prints the last login for all users of a machine similar to the way lastlog does. The login name, port, and last login time will be printed.

31.2 Configuring the Audit Daemon

Before you can actually start generating audit logs and processing them, configure the audit daemon itself. The /etc/audit/auditd.conf configuration file determines how the audit system functions when the daemon has been started. For most use cases, the default settings shipped with SUSE Linux Enterprise Server should suffice. For CAPP environments, most of these parameters need tweaking. The following list briefly introduces the parameters available:

log_file = /var/log/audit/audit.log
log_format = RAW
log_group = root
priority_boost = 4
flush = INCREMENTAL
freq = 20
num_logs = 5
disp_qos = lossy
dispatcher = /sbin/audispd
name_format = NONE
##name = mydomain
max_log_file = 6
max_log_file_action = ROTATE
space_left = 75
space_left_action = SYSLOG
action_mail_acct = root
admin_space_left = 50
admin_space_left_action = SUSPEND
disk_full_action = SUSPEND
disk_error_action = SUSPEND
##tcp_listen_port =
tcp_listen_queue = 5
tcp_max_per_addr = 1
##tcp_client_ports = 1024-65535
tcp_client_max_idle = 0
cp_client_max_idle = 0

Depending on whether you want your environment to satisfy the requirements of CAPP, you need to be extra restrictive when configuring the audit daemon. Where you need to use particular settings to meet the CAPP requirements, a CAPP Environment note tells you how to adjust the configuration.

log_file, log_format and log_group

log_file specifies the location where the audit logs should be stored. log_format determines how the audit information is written to disk and log_group defines the group that owns the log files. Possible values for log_format are raw (messages are stored exactly as the kernel sends them) or nolog (messages are discarded and not written to disk). The data sent to the audit dispatcher is not affected if you use the nolog mode. The default setting is raw and you should keep it if you want to be able to create reports and queries against the audit logs using the aureport and ausearch tools. The value for log_group can either be specified literally or using the group's ID.

Note
Note: CAPP Environment

In a CAPP environment, have the audit log reside on its own partition. By doing so, you can be sure that the space detection of the audit daemon is accurate and that you do not have other processes consuming this space.

priority_boost

Determine how much of a priority boost the audit daemon should get. Possible values are 0 to 20. The resulting nice value calculates like this: 0 - priority_boost

flush and freq

Specifies whether, how, and how often the audit logs should be written to disk. Valid values for flush are none, incremental, data, and sync. none tells the audit daemon not to make any special effort to write the audit data to disk. incremental tells the audit daemon to explicitly flush the data to disk. A frequency must be specified if incremental is used. A freq value of 20 tells the audit daemon to request that the kernel flush the data to disk after every 20 records. The data option keeps the data portion of the disk file synchronized at all times while the sync option takes care of both metadata and data.

Note
Note: CAPP Environment

In a CAPP environment, make sure that the audit trail is always fully up to date and complete. Therefore, use sync or data with the flush parameter.

num_logs

Specify the number of log files to keep if you have given rotate as the max_log_file_action. Possible values range from 0 to 99. A value less than 2 means that the log files are not rotated. As you increase the number of files to rotate, you increase the amount of work required of the audit daemon. While doing this rotation, auditd cannot always service new data arriving from the kernel as quickly, which can result in a backlog condition (triggering auditd to react according to the failure flag, described in Section 31.3, “Controlling the Audit System Using auditctl). In this situation, increasing the backlog limit is recommended. Do so by changing the value of the -b parameter in the /etc/audit/audit.rules file.

disp_qos and dispatcher

The dispatcher is started by the audit daemon during its start. The audit daemon relays the audit messages to the application specified in dispatcher. This application must be a highly trusted one, because it needs to run as root. disp_qos determines whether you allow for lossy or lossless communication between the audit daemon and the dispatcher.

If you select lossy, the audit daemon might discard some audit messages when the message queue is full. These events still get written to disk if log_format is set to raw, but they might not get through to the dispatcher. If you select lossless the audit logging to disk is blocked until there is an empty spot in the message queue. The default value is lossy.

name_format and name

name_format controls how computer names are resolved. Possible values are none (no name will be used), hostname (value returned by gethostname), fqd (fully qualified host name as received through a DNS lookup), numeric (IP address) and user. user is a custom string that needs to be defined with the name parameter.

max_log_file and max_log_file_action

max_log_file takes a numerical value that specifies the maximum file size in megabytes that the log file can reach before a configurable action is triggered. The action to be taken is specified in max_log_file_action. Possible values for max_log_file_action are ignore, syslog, suspend, rotate, and keep_logs. ignore tells the audit daemon to do nothing when the size limit is reached, syslog tells it to issue a warning and send it to syslog, and suspend causes the audit daemon to stop writing logs to disk, leaving the daemon itself still alive. rotate triggers log rotation using the num_logs setting. keep_logs also triggers log rotation, but does not use the num_log setting, so always keeps all logs.

Note
Note: CAPP Environment

To keep a complete audit trail in CAPP environments, the keep_logs option should be used. If using a separate partition to hold your audit logs, adjust max_log_file and num_logs to use the entire space available on that partition. Note that the more files that need to be rotated, the longer it takes to get back to receiving audit events.

space_left and space_left_action

space_left takes a numerical value in megabytes of remaining disk space that triggers a configurable action by the audit daemon. The action is specified in space_left_action. Possible values for this parameter are ignore, syslog, email, exec, suspend, single, and halt. ignore tells the audit daemon to ignore the warning and do nothing, syslog has it issue a warning to syslog, and email sends an e-mail to the account specified under action_mail_acct. exec plus a path to a script executes the given script. Note that it is not possible to pass parameters to the script. suspend tells the audit daemon to stop writing to disk but remain alive while single triggers the system to be brought down to single user mode. halt triggers a full shutdown of the system.

Note
Note: CAPP Environment

Make sure that space_left is set to a value that gives the administrator enough time to react to the alert and allows it to free enough disk space for the audit daemon to continue to work. Freeing disk space would involve calling aureport -t and archiving the oldest logs on a separate archiving partition or resource. The actual value for space_left depends on the size of your deployment. Set space_left_action to email.

action_mail_acct

Specify an e-mail address or alias to which any alert messages should be sent. The default setting is root, but you can enter any local or remote account as long as e-mail and the network are properly configured on your system and /usr/lib/sendmail exists.

admin_space_left and admin_space_left_action

admin_space_left takes a numerical value in megabytes of remaining disk space. The system is already running low on disk space when this limit is reached and the administrator has one last chance to react to this alert and free disk space for the audit logs. The value of admin_space_left should be lower than the value for space_left. The possible values for admin_space_left_action are the same as for space_left_action.

Note
Note: CAPP Environment

Set admin_space_left to a value that would allow the administrator's actions to be recorded. The action should be set to single.

disk_full_action

Specify which action to take when the system runs out of disk space for the audit logs. Valid values are ignore, syslog, rotate, exec, suspend, single, and halt. For an explanation of these values refer to space_left and space_left_action .

Note
Note: CAPP Environment

As the disk_full_action is triggered when there is absolutely no more room for any audit logs, you should bring the system down to single-user mode (single) or shut it down completely (halt).

disk_error_action

Specify which action to take when the audit daemon encounters any kind of disk error while writing the logs to disk or rotating the logs. The possible value are the same as for space_left_action.

Note
Note: CAPP Environment

Use syslog, single, or halt depending on your site's policies regarding the handling of any kind of hardware failure.

tcp_listen_port, tcp_listen_queue, tcp_client_ports, tcp_client_max_idle, and tcp_max_per_addr

The audit daemon can receive audit events from other audit daemons. The tcp parameters let you control incoming connections. Specify a port between 1 and 65535 with tcp_listen_port on which the auditd will listen. tcp_listen_queue lets you configure a maximum value for pending connections. Make sure not to set a value too small, since the number of pending connections may be high under certain circumstances, such as after a power outage. tcp_client_ports defines which client ports are allowed. Either specify a single port or a port range with numbers separated by a dash (for example 1-1023 for all privileged ports).

Specifying a single allowed client port may make it difficult for the client to restart their audit subsystem, as it will be unable to re-create a connection with the same host addresses and ports until the connection closure TIME_WAIT state times out. If a client does not respond anymore, auditd complains. Specify the number of seconds after which this will happen with tcp_client_max_idle. Keep in mind that this setting is valid for all clients and therefore should be higher than any individual client heartbeat setting, preferably by a factor of two. tcp_max_per_addr is a numeric value representing how many concurrent connections from one IP address are allowed.

Tip
Tip

We recommend using privileged ports for client and server to prevent non-root (CAP_NET_BIND_SERVICE) programs from binding to those ports.

When the daemon configuration in /etc/audit/auditd.conf is complete, the next step is to focus on controlling the amount of auditing the daemon does, and to assign sufficient resources and limits to the daemon so it can operate smoothly.

31.3 Controlling the Audit System Using auditctl

auditctl is responsible for controlling the status and some basic system parameters of the audit daemon. It controls the amount of auditing performed on the system. Using audit rules, auditctl controls which components of your system are subjected to the audit and to what extent they are audited. Audit rules can be passed to the audit daemon on the auditctl command line or by composing a rule set and instructing the audit daemon to process this file. By default, the auditd daemon is configured to check for audit rules under /etc/audit/audit.rules. For more details on audit rules, refer to Section 31.4, “Passing Parameters to the Audit System”.

The main auditctl commands to control basic audit system parameters are:

  • auditctl -e to enable or disable audit

  • auditctl -f to control the failure flag

  • auditctl -r to control the rate limit for audit messages

  • auditctl -b to control the backlog limit

  • auditctl -s to query the current status of the audit daemon

    Tip
    Tip

    Before running auditctl -S on your system, add -F arch=b64 to prevent the architecture mismatch warning.

The -e, -f, -r, and -b options can also be specified in the audit.rules file to avoid having to enter them each time the audit daemon is started.

Any time you query the status of the audit daemon with auditctl -s or change the status flag with auditctl -eFLAG, a status message (including information on each of the above-mentioned parameters) is printed. The following example highlights the typical audit status message.

Example 31.1: Example output of auditctl -s
AUDIT_STATUS: enabled=1 flag=2 pid=3105 rate_limit=0 backlog_limit=8192 lost=0 backlog=0
Table 31.1: Audit Status Flags

Flag

Meaning [Possible Values]

Command

enabled

Set the enable flag. [0..2] 0=disable, 1=enable, 2=enable and lock down the configuration

auditctl -e [0|1|2]

flag

Set the failure flag. [0..2] 0=silent, 1=printk, 2=panic (immediate halt without synchronizing pending data to disk)

auditctl -f [0|1|2]

pid

Process ID under which auditd is running.

rate_limit

Set a limit in messages per second. If the rate is not zero and is exceeded, the action specified in the failure flag is triggered.

auditctl -r RATE

backlog_limit

Specify the maximum number of outstanding audit buffers allowed. If all buffers are full, the action specified in the failure flag is triggered.

auditctl -b BACKLOG

lost

Count the current number of lost audit messages.

backlog

Count the current number of outstanding audit buffers.

31.4 Passing Parameters to the Audit System

Commands to control the audit system can be invoked individually from the shell using auditctl or batch read from a file using auditctl - R. This latter method is used by the init scripts to load rules from the file /etc/audit/audit.rules after the audit daemon has been started. The rules are executed in order from top to bottom. Each of these rules would expand to a separate auditctl command. The syntax used in the rules file is the same as that used for the auditctl command.

Changes made to the running audit system by executing auditctl on the command line are not persistent across system restarts. For changes to persist, add them to the /etc/audit/audit.rules file and, if they are not currently loaded into audit, restart the audit system to load the modified rule set by using the systemctl restart auditd command.

Example 31.2: Example Audit Rules—Audit System Parameters
-b 10001
-f 12
-r 103
-e 14

1

Specify the maximum number of outstanding audit buffers. Depending on the level of logging activity, you might need to adjust the number of buffers to avoid causing too heavy an audit load on your system.

2

Specify the failure flag to use. See Table 31.1, “Audit Status Flags” for possible values.

3

Specify the maximum number of messages per second that may be issued by the kernel. See Table 31.1, “Audit Status Flags” for details.

4

Enable or disable the audit subsystem.

Using audit, you can track any kind of file system access to important files, configurations or resources. You can add watches on these and assign keys to each kind of watch for better identification in the logs.

Example 31.3: Example Audit Rules—File System Auditing
-w /etc/shadow1
-w /etc -p rx2
-w /etc/passwd -k fk_passwd -p rwxa3

1

The -w option tells audit to add a watch to the file specified, in this case /etc/shadow. All system calls requesting access permissions to this file are analyzed.

2

This rule adds a watch to the /etc directory and applies permission filtering for read and execute access to this directory (-p rx). Any system call requesting any of these two permissions is analyzed. Only the creation of new files and the deletion of existing ones are logged as directory-related events. To get more specific events for files located under this particular directory, you should add a separate rule for each file. A file must exist before you add a rule containing a watch on it. Auditing files as they are created is not supported.

3

This rule adds a file watch to /etc/passwd. Permission filtering is applied for read, write, execute, and attribute change permissions. The -k option allows you to specify a key to use to filter the audit logs for this particular event later (for example with ausearch). You may use the same key on different rules to be able to group rules when searching for them. It is also possible to apply multiple keys to a rule.

System call auditing lets you track your system's behavior on a level even below the application level. When designing these rules, consider that auditing a great many system calls may increase your system load and cause you to run out of disk space. Consider carefully which events need tracking and how they can be filtered to be even more specific.

Example 31.4: Example Audit Rules—System Call Auditing
-a exit,always -S mkdir1
-a exit,always -S access -F a1=42
-a exit,always -S ipc -F a0=23
-a exit,always -S open -F success!=04
-a task,always -F auid=05
-a task,always -F uid=0 -F auid=501 -F gid=wheel6

1

This rule activates auditing for the mkdir system call. The -a option adds system call rules. This rule triggers an event whenever the mkdir system call is entered (exit, always). The -S option specifies the system call to which this rule should be applied.

2

This rule adds auditing to the access system call, but only if the second argument of the system call (mode) is 4 (R_OK). exit,always tells audit to add an audit context to this system call when entering it, and to write out a report when it gets audited.

3

This rule adds an audit context to the IPC multiplexed system call. The specific ipc system call is passed as the first syscall argument and can be selected using -F a0=IPC_CALL_NUMBER.

4

This rule audits failed attempts to call open.

5

This rule is an example of a task rule (keyword: task). It is different from the other rules above in that it applies to processes that are forked or cloned. To filter these kind of events, you can only use fields that are known at fork time, such as UID, GID, and AUID. This example rule filters for all tasks carrying an audit ID of 0.

6

This last rule makes heavy use of filters. All filter options are combined with a logical AND operator, meaning that this rule applies to all tasks that carry the audit ID of 501, run as root, and have wheel as the group. A process is given an audit ID on user login. This ID is then handed down to any child process started by the initial process of the user. Even if the user changes his identity, the audit ID stays the same and allows tracing actions to the original user.

Tip
Tip: Filtering System Call Arguments

For more details on filtering system call arguments, refer to Section 33.6, “Filtering System Call Arguments”.

You cannot only add rules to the audit system, but also remove them. There are different methods for deleting the entire rule set at once or for deleting system call rules or file and directory watches:

Example 31.5: Deleting Audit Rules and Events
-D1
-d exit,always -S mkdir2
-W /etc3

1

Clear the queue of audit rules and delete any preexisting rules. This rule is used as the first rule in /etc/audit/audit.rules files to make sure that the rules that are about to be added do not clash with any preexisting ones. The auditctl -D command is also used before doing an autrace to avoid having the trace rules clash with any rules present in the audit.rules file.

2

This rule deletes a system call rule. The -d option must precede any system call rule that needs to be deleted from the rule queue, and must match exactly.

3

This rule tells audit to discard the rule with the directory watch on /etc from the rules queue. This rule deletes any rule containing a directory watch on /etc, regardless of any permission filtering or key options.

To get an overview of which rules are currently in use in your audit setup, run auditctl -l. This command displays all rules with one rule per line.

Example 31.6: Listing Rules with auditctl -l
exit,always watch=/etc perm=rx
exit,always watch=/etc/passwd perm=rwxa key=fk_passwd
exit,always watch=/etc/shadow perm=rwxa
exit,always syscall=mkdir
exit,always a1=4 (0x4) syscall=access
exit,always a0=2 (0x2) syscall=ipc
exit,always success!=0 syscall=open
Note
Note: Creating Filter Rules

You can build very sophisticated audit rules by using the various filter options. Refer to the auditctl(8) man page for more information about the options available for building audit filter rules, and audit rules in general.

31.5 Understanding the Audit Logs and Generating Reports

To understand what the aureport utility does, it is vital to know how the logs generated by the audit daemon are structured, and what exactly is recorded for an event. Only then can you decide which report types are most appropriate for your needs.

31.5.1 Understanding the Audit Logs

The following examples highlight two typical events that are logged by audit and how their trails in the audit log are read. The audit log or logs (if log rotation is enabled) are stored in the /var/log/audit directory. The first example is a simple less command. The second example covers a great deal of PAM activity in the logs when a user tries to remotely log in to a machine running audit.

Example 31.7: A Simple Audit Event—Viewing the Audit Log
type=SYSCALL msg=audit(1234874638.599:5207): arch=c000003e syscall=2 success=yes exit=4 a0=62fb60 a1=0 a2=31 a3=0 items=1 ppid=25400 pid
=25616 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts1 ses=1164 comm="less" exe="/usr/bin/less" key="doc_log"
type=CWD msg=audit(1234874638.599:5207):  cwd="/root"
type=PATH msg=audit(1234874638.599:5207): item=0 name="/var/log/audit/audit.log" inode=1219041 dev=08:06 mode=0100644 ouid=0 ogid=0 rdev=00:00

The above event, a simple less /var/log/audit/audit.log, wrote three messages to the log. All of them are closely linked together and you would not be able to make sense of one of them without the others. The first message reveals the following information:

type

The type of event recorded. In this case, it assigns the SYSCALL type to an event triggered by a system call. The CWD event was recorded to record the current working directory at the time of the syscall. A PATH event is generated for each path passed to the system call. The open system call takes only one path argument, so only generates one PATH event. It is important to understand that the PATH event reports the path name string argument without any further interpretation, so a relative path requires manual combination with the path reported by the CWD event to determine the object accessed.

msg

A message ID enclosed in brackets. The ID splits into two parts. All characters before the : represent a Unix epoch time stamp. The number after the colon represents the actual event ID. All events that are logged from one application's system call have the same event ID. If the application makes a second system call, it gets another event ID.

arch

References the CPU architecture of the system call. Decode this information using the -i option on any of your ausearch commands when searching the logs.

syscall

The type of system call as it would have been printed by an strace on this particular system call. This data is taken from the list of system calls under /usr/include/asm/unistd.h and may vary depending on the architecture. In this case, syscall=2 refers to the open system call (see man open(2)) invoked by the less application.

success

Whether the system call succeeded or failed.

exit

The exit value returned by the system call. For the open system call used in this example, this is the file descriptor number. This varies by system call.

a0 to a3

The first four arguments to the system call in numeric form. The values of these are system call dependent. In this example (an open system call), the following are used:

a0=62fb60 a1=8000 a2=31 a3=0

a0 is the start address of the passed path name. a1 is the flags. 8000 in hex notation translates to 100000 in octal notation, which in turn translates to O_LARGEFILE. a2 is the mode, which, because O_CREAT was not specified, is unused. a3 is not passed by the open system call. Check the manual page of the relevant system call to find out which arguments are used with it.

items

The number of strings passed to the application.

ppid

The process ID of the parent of the process analyzed.

pid

The process ID of the process analyzed.

auid

The audit ID. A process is given an audit ID on user login. This ID is then handed down to any child process started by the initial process of the user. Even if the user changes his identity (for example, becomes root), the audit ID stays the same. Thus you can always trace actions to the original user who logged in.

uid

The user ID of the user who started the process. In this case, 0 for root.

gid

The group ID of the user who started the process. In this case, 0 for root.

euid, suid, fsuid

Effective user ID, set user ID, and file system user ID of the user that started the process.

egid, sgid, fsgid

Effective group ID, set group ID, and file system group ID of the user that started the process.

tty

The terminal from which the application was started. In this case, a pseudo-terminal used in an SSH session.

ses

The login session ID. This process attribute is set when a user logs in and can tie any process to a particular user login.

comm

The application name under which it appears in the task list.

exe

The resolved path name to the binary program.

subj

auditd records whether the process is subject to any security context, such as AppArmor. unconstrained, as in this case, means that the process is not confined with AppArmor. If the process had been confined, the binary path name plus the AppArmor profile mode would have been logged.

key

If you are auditing many directories or files, assign key strings to each of these watches. You can use these keys with ausearch to search the logs for events of this type only.

The second message triggered by the example less call does not reveal anything apart from the current working directory when the less command was executed.

The third message reveals the following (the type and message flags have already been introduced):

item

In this example, item references the a0 argument—a path—that is associated with the original SYSCALL message. Had the original call had more than one path argument (such as a cp or mv command), an additional PATH event would have been logged for the second path argument.

name

Refers to the path name passed as an argument to the open system call.

inode

Refers to the inode number corresponding to name.

dev

Specifies the device on which the file is stored. In this case, 08:06, which stands for /dev/sda1 or first partition on the first IDE device.

mode

Numerical representation of the file's access permissions. In this case, root has read and write permissions and his group (root) has read access while the entire rest of the world cannot access the file.

ouid and ogid

Refer to the UID and GID of the inode itself.

rdev

Not applicable for this example. The rdev entry only applies to block or character devices, not to files.

Example 31.8, “An Advanced Audit Event—Login via SSH” highlights the audit events triggered by an incoming SSH connection. Most of the messages are related to the PAM stack and reflect the different stages of the SSH PAM process. Several of the audit messages carry nested PAM messages in them that signify that a particular stage of the PAM process has been reached. Although the PAM messages are logged by audit, audit assigns its own message type to each event:

Example 31.8: An Advanced Audit Event—Login via SSH
type=USER_AUTH msg=audit(1234877011.791:7731): user pid=26127 uid=0 1
auid=4294967295 ses=4294967295 msg='op=PAM:authentication acct="root" exe="/usr/sbin/sshd"
(hostname=jupiter.example.com, addr=192.168.2.100, terminal=ssh res=success)'
type=USER_ACCT msg=audit(1234877011.795:7732): user pid=26127 uid=0 2
auid=4294967295 ses=4294967295 msg='op=PAM:accounting acct="root" exe="/usr/sbin/sshd"
(hostname=jupiter.example.com, addr=192.168.2.100, terminal=ssh res=success)'
type=CRED_ACQ msg=audit(1234877011.799:7733): user pid=26125 uid=0 3
auid=4294967295 ses=4294967295 msg='op=PAM:setcred acct="root" exe="/usr/sbin/sshd"
(hostname=jupiter.example.com, addr=192.168.2.100, terminal=/dev/pts/0 res=success)'
type=LOGIN msg=audit(1234877011.799:7734): login pid=26125 uid=0
old auid=4294967295 new auid=0 old ses=4294967295 new ses=1172
type=USER_START msg=audit(1234877011.799:7735): user pid=26125 uid=0 4
auid=0 ses=1172 msg='op=PAM:session_open acct="root" exe="/usr/sbin/sshd"
(hostname=jupiter.example.com, addr=192.168.2.100, terminal=/dev/pts/0 res=success)'
type=USER_LOGIN msg=audit(1234877011.823:7736): user pid=26128 uid=0 5
auid=0 ses=1172 msg='uid=0: exe="/usr/sbin/sshd"
(hostname=jupiter.example.com, addr=192.168.2.100, terminal=/dev/pts/0 res=success)'
type=CRED_REFR msg=audit(1234877011.828:7737): user pid=26128 uid=0 6
auid=0 ses=1172 msg='op=PAM:setcred acct="root" exe="/usr/sbin/sshd"
(hostname=jupiter.example.com, addr=192.168.2.100, terminal=/dev/pts/0 res=success)'

1

PAM reports that is has successfully requested user authentication for root from a remote host (jupiter.example.com, 192.168.2.100). The terminal where this is happening is ssh.

2

PAM reports that it has successfully determined whether the user is authorized to log in.

3

PAM reports that the appropriate credentials to log in have been acquired and that the terminal changed to a normal terminal (/dev/pts0).

4

PAM reports that it has successfully opened a session for root.

5

The user has successfully logged in. This event is the one used by aureport -l to report about user logins.

6

PAM reports that the credentials have been successfully reacquired.

31.5.2 Generating Custom Audit Reports

The raw audit reports stored in the /var/log/audit directory tend to become very bulky and hard to understand. To more easily find relevant messages, use the aureport utility and create custom reports.

The following use cases highlight a few of the possible report types that you can generate with aureport:

Read Audit Logs from Another File

When the audit logs have moved to another machine or when you want to analyze the logs of several machines on your local machine without wanting to connect to each of these individually, move the logs to a local file and have aureport analyze them locally:

aureport -if myfile

Summary Report
======================
Range of time in logs: 03/02/09 14:13:38.225 - 17/02/09 14:52:27.971
Selected time for report: 03/02/09 14:13:38 - 17/02/09 14:52:27.971
Number of changes in configuration: 13
Number of changes to accounts, groups, or roles: 0
Number of logins: 6
Number of failed logins: 13
Number of authentications: 7
Number of failed authentications: 573
Number of users: 1
Number of terminals: 9
Number of host names: 4
Number of executables: 17
Number of files: 279
Number of AVC's: 0
Number of MAC events: 0
Number of failed syscalls: 994
Number of anomaly events: 0
Number of responses to anomaly events: 0
Number of crypto events: 0
Number of keys: 2
Number of process IDs: 1211
Number of events: 5320

The above command, aureport without any arguments, provides only the standard general summary report generated from the logs contained in myfile. To create more detailed reports, combine the -if option with any of the options below. For example, generate a login report that is limited to a certain time frame:

aureport -l -ts 14:00 -te 15:00 -if myfile

Login Report
============================================
# date time auid host term exe success event
============================================
1. 17/02/09 14:21:09 root: 192.168.2.100 sshd /usr/sbin/sshd no 7718
2. 17/02/09 14:21:15 0 jupiter /dev/pts/3 /usr/sbin/sshd yes 7724
Convert Numeric Entities to Text

Some information, such as user IDs, are printed in numeric form. To convert these into a human-readable text format, add the -i option to your aureport command.

Create a Rough Summary Report

If you are interested in the current audit statistics (events, logins, processes, etc.), run aureport without any other option.

Create a Summary Report of Failed Events

If you want to break down the overall statistics of plain aureport to the statistics of failed events, use aureport --failed:

aureport --failed

Failed Summary Report
======================
Range of time in logs: 03/02/09 14:13:38.225 - 17/02/09 14:57:35.183
Selected time for report: 03/02/09 14:13:38 - 17/02/09 14:57:35.183
Number of changes in configuration: 0
Number of changes to accounts, groups, or roles: 0
Number of logins: 0
Number of failed logins: 13
Number of authentications: 0
Number of failed authentications: 574
Number of users: 1
Number of terminals: 5
Number of host names: 4
Number of executables: 11
Number of files: 77
Number of AVC's: 0
Number of MAC events: 0
Number of failed syscalls: 994
Number of anomaly events: 0
Number of responses to anomaly events: 0
Number of crypto events: 0
Number of keys: 2
Number of process IDs: 708
Number of events: 1583
Create a Summary Report of Successful Events

If you want to break down the overall statistics of a plain aureport to the statistics of successful events, use aureport --success:

aureport --success

Success Summary Report
======================
Range of time in logs: 03/02/09 14:13:38.225 - 17/02/09 15:00:01.535
Selected time for report: 03/02/09 14:13:38 - 17/02/09 15:00:01.535
Number of changes in configuration: 13
Number of changes to accounts, groups, or roles: 0
Number of logins: 6
Number of failed logins: 0
Number of authentications: 7
Number of failed authentications: 0
Number of users: 1
Number of terminals: 7
Number of host names: 3
Number of executables: 16
Number of files: 215
Number of AVC's: 0
Number of MAC events: 0
Number of failed syscalls: 0
Number of anomaly events: 0
Number of responses to anomaly events: 0
Number of crypto events: 0
Number of keys: 2
Number of process IDs: 558
Number of events: 3739
Create Summary Reports

In addition to the dedicated summary reports (main summary and failed and success summary), use the --summary option with most of the other options to create summary reports for a particular area of interest only. Not all reports support this option, however. This example creates a summary report for user login events:

aureport -u -i --summary

User Summary Report
===========================
total  auid
===========================
5640  root
13  tux
3  wilber
Create a Report of Events

To get an overview of the events logged by audit, use the aureport -e command. This command generates a numbered list of all events including date, time, event number, event type, and audit ID.

aureport -e -ts 14:00 -te 14:21

Event Report
===================================
# date time event type auid success
===================================
1. 17/02/09 14:20:27 7462 DAEMON_START 0 yes
2. 17/02/09 14:20:27 7715 CONFIG_CHANGE 0 yes
3. 17/02/09 14:20:57 7716 USER_END 0 yes
4. 17/02/09 14:20:57 7717 CRED_DISP 0 yes
5. 17/02/09 14:21:09 7718 USER_LOGIN -1 no
6. 17/02/09 14:21:15 7719 USER_AUTH -1 yes
7. 17/02/09 14:21:15 7720 USER_ACCT -1 yes
8. 17/02/09 14:21:15 7721 CRED_ACQ -1 yes
9. 17/02/09 14:21:15 7722 LOGIN 0 yes
10. 17/02/09 14:21:15 7723 USER_START 0 yes
11. 17/02/09 14:21:15 7724 USER_LOGIN 0 yes
12. 17/02/09 14:21:15 7725 CRED_REFR 0 yes
Create a Report from All Process Events

To analyze the log from a process's point of view, use the aureport -p command. This command generates a numbered list of all process events including date, time, process ID, name of the executable, system call, audit ID, and event number.

aureport -p

Process ID Report
======================================
# date time pid exe syscall auid event
======================================
1. 13/02/09 15:30:01 32742 /usr/sbin/cron 0 0 35
2. 13/02/09 15:30:01 32742 /usr/sbin/cron 0 0 36
3. 13/02/09 15:38:34 32734 /usr/lib/gdm/gdm-session-worker 0 -1 37
Create a Report from All System Call Events

To analyze the audit log from a system call's point of view, use the aureport -s command. This command generates a numbered list of all system call events including date, time, number of the system call, process ID, name of the command that used this call, audit ID, and event number.

aureport -s

Syscall Report
=======================================
# date time syscall pid comm auid event
=======================================
1. 16/02/09 17:45:01 2 20343 cron -1 2279
2. 16/02/09 17:45:02 83 20350 mktemp 0 2284
3. 16/02/09 17:45:02 83 20351 mkdir 0 2285
Create a Report from All Executable Events

To analyze the audit log from an executable's point of view, use the aureport -x command. This command generates a numbered list of all executable events including date, time, name of the executable, the terminal it is run in, the host executing it, the audit ID, and event number.

aureport -x

Executable Report
====================================
# date time exe term host auid event
====================================
1. 13/02/09 15:08:26 /usr/sbin/sshd sshd 192.168.2.100 -1 12
2. 13/02/09 15:08:28 /usr/lib/gdm/gdm-session-worker :0 ? -1 13
3. 13/02/09 15:08:28 /usr/sbin/sshd ssh 192.168.2.100 -1 14
Create a Report about Files

To generate a report from the audit log that focuses on file access, use the aureport -f command. This command generates a numbered list of all file-related events including date, time, name of the accessed file, number of the system call accessing it, success or failure of the command, the executable accessing the file, audit ID, and event number.

aureport -f

File Report
===============================================
# date time file syscall success exe auid event
===============================================
1. 16/02/09 17:45:01 /etc/shadow 2 yes /usr/sbin/cron -1 2279
2. 16/02/09 17:45:02 /tmp/ 83 yes /bin/mktemp 0 2284
3. 16/02/09 17:45:02 /var 83 no /bin/mkdir 0 2285
Create a Report about Users

To generate a report from the audit log that illustrates which users are running what executables on your system, use the aureport -u command. This command generates a numbered list of all user-related events including date, time, audit ID, terminal used, host, name of the executable, and an event ID.

aureport -u

User ID Report
====================================
# date time auid term host exe event
====================================
1. 13/02/09 15:08:26 -1 sshd 192.168.2.100 /usr/sbin/sshd 12
2. 13/02/09 15:08:28 -1 :0 ? /usr/lib/gdm/gdm-session-worker 13
3. 14/02/09 08:25:39 -1 ssh 192.168.2.101 /usr/sbin/sshd 14
Create a Report about Logins

To create a report that focuses on login attempts to your machine, run the aureport -l command. This command generates a numbered list of all login-related events including date, time, audit ID, host and terminal used, name of the executable, success or failure of the attempt, and an event ID.

aureport -l -i

Login Report
============================================
# date time auid host term exe success event
============================================
1. 13/02/09 15:08:31 tux: 192.168.2.100 sshd /usr/sbin/sshd no 19
2. 16/02/09 12:39:05 root: 192.168.2.101 sshd /usr/sbin/sshd no 2108
3. 17/02/09 15:29:07 geeko: ? tty3 /bin/login yes 7809
Limit a Report to a Certain Time Frame

To analyze the logs for a particular time frame, such as only the working hours of Feb 16, 2009, first find out whether this data is contained in the current audit.log or whether the logs have been rotated in by running aureport -t:

aureport -t

Log Time Range Report
=====================
/var/log/audit/audit.log: 03/02/09 14:13:38.225 - 17/02/09 15:30:01.636

The current audit.log contains all the desired data. Otherwise, use the -if option to point the aureport commands to the log file that contains the needed data.

Then, specify the start date and time and the end date and time of the desired time frame and combine it with the report option needed. This example focuses on login attempts:

aureport -ts 02/16/09 8:00 -te 02/16/09 18:00 -l

Login Report
============================================
# date time auid host term exe success event
============================================
1. 16/02/09 12:39:05 root: 192.168.2.100 sshd /usr/sbin/sshd no 2108
2. 16/02/09 12:39:12 0 192.168.2.100 /dev/pts/1 /usr/sbin/sshd yes 2114
3. 16/02/09 13:09:28 root: 192.168.2.100 sshd /usr/sbin/sshd no 2131
4. 16/02/09 13:09:32 root: 192.168.2.100 sshd /usr/sbin/sshd no 2133
5. 16/02/09 13:09:37 0 192.168.2.100 /dev/pts/2 /usr/sbin/sshd yes 2139

The start date and time are specified with the -ts option. Any event that has a time stamp equal to or after your given start time appears in the report. If you omit the date, aureport assumes that you meant today. If you omit the time, it assumes that the start time should be midnight of the date specified.

Specify the end date and time with the -te option. Any event that has a time stamp equal to or before your given event time appears in the report. If you omit the date, aureport assumes that you meant today. If you omit the time, it assumes that the end time should be now. Use the same format for the date and time as for -ts.

All reports except the summary ones are printed in column format and sent to STDOUT, which means that this data can be written to other commands very easily. The visualization scripts introduced in Section 31.8, “Visualizing Audit Data” are examples of how to further process the data generated by audit.

31.6 Querying the Audit Daemon Logs with ausearch

The aureport tool helps you to create overall summaries of what is happening on the system, but if you are interested in the details of a particular event, ausearch is the tool to use.

ausearch allows you to search the audit logs using special keys and search phrases that relate to most of the flags that appear in event messages in /var/log/audit/audit.log. Not all record types contain the same search phrases. There are no hostname or uid entries in a PATH record, for example.

When searching, make sure that you choose appropriate search criteria to catch all records you need. On the other hand, you could be searching for a specific type of record and still get various other related records along with it. This is caused by different parts of the kernel contributing additional records for events that are related to the one to find. For example, you would always get a PATH record along with the SYSCALL record for an open system call.

Tip
Tip: Using Multiple Search Options

Any of the command line options can be combined with logical AND operators to narrow down your search.

Read Audit Logs from Another File

When the audit logs have moved to another machine or when you want to analyze the logs of several machines on your local machine without wanting to connect to each of these individually, move the logs to a local file and have ausearch search them locally:

ausearch - option -if myfile
Convert Numeric Results into Text

Some information, such as user IDs are printed in numeric form. To convert these into human readable text format, add the -i option to your ausearch command.

Search by Audit Event ID

If you have previously run an audit report or done an autrace, you should analyze the trail of a particular event in the log. Most of the report types described in Section 31.5, “Understanding the Audit Logs and Generating Reports” include audit event IDs in their output. An audit event ID is the second part of an audit message ID, which consists of a Unix epoch time stamp and the audit event ID separated by a colon. All events that are logged from one application's system call have the same event ID. Use this event ID with ausearch to retrieve this event's trail from the log.

Use a command similar to the following:

ausearch -a 5207
----
time->Tue Feb 17 13:43:58 2009
type=PATH msg=audit(1234874638.599:5207): item=0 name="/var/log/audit/audit.log" inode=1219041 dev=08:06 mode=0100644 ouid=0 ogid=0 rdev=00:00
type=CWD msg=audit(1234874638.599:5207):  cwd="/root"
type=SYSCALL msg=audit(1234874638.599:5207): arch=c000003e syscall=2 success=yes exit=4 a0=62fb60 a1=0 a2=31 a3=0 items=1 ppid=25400 pid=25616 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts1 ses=1164 comm="less" exe="/usr/bin/less" key="doc_log"

The ausearch -a command grabs all records in the logs that are related to the audit event ID provided and displays them. This option can be combined with any other option.

Search by Message Type

To search for audit records of a particular message type, use the ausearch -m MESSAGE_TYPE command. Examples of valid message types include PATH, SYSCALL, and USER_LOGIN. Running ausearch -m without a message type displays a list of all message types.

Search by Login ID

To view records associated with a particular login user ID, use the ausearch -ul command. It displays any records related to the user login ID specified provided that user had been able to log in successfully.

Search by User ID

View records related to any of the user IDs (both user ID and effective user ID) with ausearch -ua. View reports related to a particular user ID with ausearch -ui UID. Search for records related to a particular effective user ID, use the ausearch -ue EUID. Searching for a user ID means the user ID of the user creating a process. Searching for an effective user ID means the user ID and privileges that are required to run this process.

Search by Group ID

View records related to any of the group IDs (both group ID and effective group ID) with the ausearch -ga command. View reports related to a particular user ID with ausearch -gi GID. Search for records related to a particular effective group ID, use ausearch -ge EGID.

Search by Command Line Name

View records related to a certain command, using the ausearch -c COMM_NAME command, for example, ausearch -c less for all records related to the less command.

Search by Executable Name

View records related to a certain executable with the ausearch -x EXE command, for example ausearch -x /usr/bin/less for all records related to the /usr/bin/less executable.

Search by System Call Name

View records related to a certain system call with the ausearch -sc SYSCALL command, for example, ausearch -sc open for all records related to the open system call.

Search by Process ID

View records related to a certain process ID with the ausearch -p PID command, for example ausearch -p 13368 for all records related to this process ID.

Search by Event or System Call Success Value

View records containing a certain system call success value with ausearch -sv SUCCESS_VALUE, for example, ausearch -sv yes for all successful system calls.

Search by File Name

View records containing a certain file name with ausearch -f FILE_NAME, for example, ausearch -f /foo/bar for all records related to the /foo/bar file. Using the file name alone would work as well, but using relative paths does not work.

Search by Terminal

View records of events related to a certain terminal only with ausearch -tm TERM, for example, ausearch -tm ssh to view all records related to events on the SSH terminal and ausearch -tm tty to view all events related to the console.

Search by Host Name

View records related to a certain remote host name with ausearch -hn HOSTNAME, for example, ausearch -hn jupiter.example.com. You can use a host name, fully qualified domain name, or numeric network address.

Search by Key Field

View records that contain a certain key assigned in the audit rule set to identify events of a particular type. Use the ausearch -k KEY_FIELD, for example, ausearch -k CFG_etc to display any records containing the CFG_etc key.

Search by Word

View records that contain a certain string assigned in the audit rule set to identify events of a particular type. The whole string will be matched on file name, host name, and terminal. Use the ausearch -w WORD.

Limit a Search to a Certain Time Frame

Use -ts and -te to limit the scope of your searches to a certain time frame. The -ts option is used to specify the start date and time and the -te option is used to specify the end date and time. These options can be combined with any of the above. The use of these options is similar to use with aureport.

31.7 Analyzing Processes with autrace

In addition to monitoring your system using the rules you set up, you can also perform dedicated audits of individual processes using the autrace command. autrace works similarly to the strace command, but gathers slightly different information. The output of autrace is written to /var/log/audit/audit.log and does not look any different from the standard audit log entries.

When performing an autrace on a process, make sure that any audit rules are purged from the queue to avoid these rules clashing with the ones autrace adds itself. Delete the audit rules with the auditctl -D command. This stops all normal auditing.

auditctl -D

No rules

autrace /usr/bin/less

Waiting to execute: /usr/bin/less
Cleaning up...
No rules
Trace complete. You can locate the records with 'ausearch -i -p 7642'

Always use the full path to the executable to track with autrace. After the trace is complete, autrace provides the event ID of the trace, so you can analyze the entire data trail with ausearch. To restore the audit system to use the audit rule set again, restart the audit daemon with systemctl restart auditd.

31.8 Visualizing Audit Data

Neither the data trail in /var/log/audit/audit.log nor the different report types generated by aureport, described in Section 31.5.2, “Generating Custom Audit Reports”, provide an intuitive reading experience to the user. The aureport output is formatted in columns and thus easily available to any sed, Perl, or awk scripts that users might connect to the audit framework to visualize the audit data.

The visualization scripts (see Section 32.6, “Configuring Log Visualization”) are one example of how to use standard Linux tools available with SUSE Linux Enterprise Server or any other Linux distribution to create easy-to-read audit output. The following examples help you understand how the plain audit reports can be transformed into human readable graphics.

The first example illustrates the relationship of programs and system calls. To get to this kind of data, you need to determine the appropriate aureport command that delivers the source data from which to generate the final graphic:

aureport -s -i

Syscall Report
=======================================
# date time syscall pid comm auid event
=======================================
1. 16/02/09 17:45:01 open 20343 cron unset 2279
2. 16/02/09 17:45:02 mkdir 20350 mktemp root 2284
3. 16/02/09 17:45:02 mkdir 20351 mkdir root 2285
...

The first thing that the visualization script needs to do on this report is to extract only those columns that are of interest, in this example, the syscall and the comm columns. The output is sorted and duplicates removed then the final output is written into the visualization program itself:

LC_ALL=C aureport -s -i | awk '/^[0-9]/ { print $6" "$4 }' | sort | uniq | mkgraph
Flow Graph—Program versus System Call Relationship
Figure 31.2: Flow Graph—Program versus System Call Relationship

The second example illustrates the different types of events and how many of each type have been logged. The appropriate aureport command to extract this kind of information is aureport -e:

aureport -e -i --summary

Event Summary Report
======================
total  type
======================
2434  SYSCALL
816  USER_START
816  USER_ACCT
814  CRED_ACQ
810  LOGIN
806  CRED_DISP
779  USER_END
99  CONFIG_CHANGE
52  USER_LOGIN

Because this type of report already contains a two column output, it is only fed into the visualization script and transformed into a bar chart.

aureport -e -i --summary  | mkbar events
Bar Chart—Common Event Types
Figure 31.3: Bar Chart—Common Event Types

For background information about the visualization of audit data, refer to the Web site of the audit project at http://people.redhat.com/sgrubb/audit/visualize/index.html.

31.9 Relaying Audit Event Notifications

The auditing system also allows external applications to access and use the auditd daemon in real time. This feature is provided by so called audit dispatcher which allows, for example, intrusion detection systems to use auditd to receive enhanced detection information.

audispd is a daemon which controls the audit dispatcher. It is normally started by auditd. audispd takes audit events and distributes them to the programs which want to analyze them in real time. Configuration of auditd is stored in /etc/audisp/audispd.conf. The file has the following options:

q_depth

Specifies the size of the event dispatcher internal queue. If syslog complains about audit events getting dropped, increase this value. Default is 80.

overflow_action

Specifies the way the audit daemon will react to the internal queue overflow. Possible values are ignore (nothing happens), syslog (issues a warning to syslog), suspend (audispd will stop processing events), single (the computer system will be put in single user mode), or halt (shuts the system down).

priority_boost

Specifies the priority for the audit event dispatcher (in addition to the audit daemon priority itself). Default is 4 which means no change in priority.

name_format

Specifies the way the computer node name is inserted into the audit event. Possible values are none (no computer name is inserted), hostname (name returned by the gethostname system call), fqd (fully qualified domain name of the machine), numeric (IP address of the machine), or user (user defined string from the name option). Default is none.

name

Specifies a user defined string which identifies the machine. The name_format option must be set to user, otherwise this option is ignored.

max_restarts

A non-negative number that tells the audit event dispatcher how many times it can try to restart a crashed plug-in. The default is 10.

Example 31.9: Example /etc/audisp/audispd.conf
  q_depth = 80
  overflow_action = SYSLOG
  priority_boost = 4
  name_format = HOSTNAME
  #name = mydomain

The plug-in programs install their configuration files in a special directory dedicated to audispd plug-ins. It is /etc/audisp/plugins.d by default. The plug-in configuration files have the following options:

active

Specifies if the program will use audispd. Possible values are yes or no.

direction

Specifies the way the plug-in was designed to communicate with audit. It informs the event dispatcher in which directions the events flow. Possible values are in or out.

path

Specifies the absolute path to the plug-in executable. In case of internal plug-ins, this option specifies the plug-in name.

type

Specifies the way the plug-in is to be run. Possible values are builtin or always. Use builtin for internal plug-ins (af_unix and syslog) and always for most (if not all) other plug-ins. Default is always.

args

Specifies the argument that is passed to the plug-in program. Normally, plug-in programs read their arguments from their configuration file and do not need to receive any arguments. There is a limit of 2 arguments.

format

Specifies the format of data that the audit dispatcher passes to the plug-in program. Valid options are binary or string. binary passes the data exactly as the event dispatcher receives them from the audit daemon. string instructs the dispatcher to change the event into a string that is parsable by the audit parsing library. Default is string.

Example 31.10: Example /etc/audisp/plugins.d/syslog.conf
  active = no
  direction = out
  path = builtin_syslog
  type = builtin
  args = LOG_INFO
  format = string

32 Setting Up the Linux Audit Framework

  • Filename: audit_setup.xml
  • ID: cha.audit.setup

This chapter shows how to set up a simple audit scenario. Every step involved in configuring and enabling audit is explained in detail. After you have learned to set up audit, consider a real-world example scenario in Chapter 33, Introducing an Audit Rule Set.

To set up audit on SUSE Linux Enterprise Server, you need to complete the following steps:

Procedure 32.1: Setting Up the Linux Audit Framework
  1. Make sure that all required packages are installed: audit, audit-libs, and optionally audit-libs-python. To use the log visualization as described in Section 32.6, “Configuring Log Visualization”, install gnuplot and graphviz from the SUSE Linux Enterprise Server media.

  2. Determine the components to audit. Refer to Section 32.1, “Determining the Components to Audit” for details.

  3. Check or modify the basic audit daemon configuration. Refer to Section 32.2, “Configuring the Audit Daemon” for details.

  4. Enable auditing for system calls. Refer to Section 32.3, “Enabling Audit for System Calls” for details.

  5. Compose audit rules to suit your scenario. Refer to Section 32.4, “Setting Up Audit Rules” for details.

  6. Generate logs and configure tailor-made reports. Refer to Section 32.5, “Configuring Audit Reports” for details.

  7. Configure optional log visualization. Refer to Section 32.6, “Configuring Log Visualization” for details.

Important
Important: Controlling the Audit Daemon

Before configuring any of the components of the audit system, make sure that the audit daemon is not running by entering systemctl status auditd as root. On a default SUSE Linux Enterprise Server system, audit is started on boot, so you need to turn it off by entering systemctl stop auditd. Start the daemon after configuring it with systemctl start auditd.

32.1 Determining the Components to Audit

Before starting to create your own audit configuration, determine to which degree you want to use it. Check the following general rules to determine which use case best applies to you and your requirements:

32.2 Configuring the Audit Daemon

The basic setup of the audit daemon is done by editing /etc/audit/auditd.conf. You may also use YaST to configure the basic settings by calling YaST › Security and Users › Linux Audit Framework (LAF). Use the tabs Log File and Disk Space for configuration.

log_file = /var/log/audit/audit.log
log_format = RAW
log_group = root
priority_boost = 4
flush = INCREMENTAL
freq = 20
num_logs = 5
disp_qos = lossy
dispatcher = /sbin/audispd
name_format = NONE
##name = mydomain
max_log_file = 6
max_log_file_action = ROTATE
space_left = 75
space_left_action = SYSLOG
action_mail_acct = root
admin_space_left = 50
admin_space_left_action = SUSPEND
disk_full_action = SUSPEND
disk_error_action = SUSPEND
##tcp_listen_port =
tcp_listen_queue = 5
tcp_max_per_addr = 1
##tcp_client_ports = 1024-65535
tcp_client_max_idle = 0
cp_client_max_idle = 0

The default settings work reasonably well for many setups. Some values, such as num_logs, max_log_file, space_left, and admin_space_left depend on the size of your deployment. If disk space is limited, you should reduce the number of log files to keep if they are rotated and you should get an earlier warning if disk space is running out. For a CAPP-compliant setup, adjust the values for log_file, flush, max_log_file, max_log_file_action, space_left, space_left_action, admin_space_left, admin_space_left_action, disk_full_action, and disk_error_action, as described in Section 31.2, “Configuring the Audit Daemon”. An example CAPP-compliant configuration looks like this:

log_file = PATH_TO_SEPARATE_PARTITION/audit.log
log_format = RAW
priority_boost = 4
flush = SYNC                       ### or DATA
freq = 20
num_logs = 4
dispatcher = /sbin/audispd
disp_qos = lossy
max_log_file = 5
max_log_file_action = KEEP_LOGS
space_left = 75
space_left_action = EMAIL
action_mail_acct = root
admin_space_left = 50
admin_space_left_action = SINGLE   ### or HALT
disk_full_action = SUSPEND         ### or HALT
disk_error_action = SUSPEND        ### or HALT

The ### precedes comments where you can choose from several options. Do not add the comments to your actual configuration files.

Tip
Tip: For More Information

Refer to Section 31.2, “Configuring the Audit Daemon” for detailed background information about the auditd.conf configuration parameters.

32.3 Enabling Audit for System Calls

If the audit framework is not installed, install the audit package. A standard SUSE Linux Enterprise Server system does not have auditd running by default. Enable it with:

systemctl enable auditd

There are different levels of auditing activity available:

Basic Logging

Out of the box (without any further configuration) auditd logs only events concerning its own configuration changes to /var/log/audit/audit.log. No events (file access, system call, etc.) are generated by the kernel audit component until requested by auditctl. However, other kernel components and modules may log audit events outside of the control of auditctl and these appear in the audit log. By default, the only module that generates audit events is AppArmor.

Advanced Logging with System Call Auditing

To audit system calls and get meaningful file watches, you need to enable audit contexts for system calls.

As you need system call auditing capabilities even when you are configuring plain file or directory watches, you need to enable audit contexts for system calls. To enable audit contexts for the duration of the current session only, execute auditctl -e 1 as root. To disable this feature, execute auditctl -e 0 as root.

The audit contexts are enabled by default. To turn this feature off temporarily, use auditctl -e 0.

32.4 Setting Up Audit Rules

Using audit rules, determine which aspects of the system should be analyzed by audit. Normally this includes important databases and security-relevant configuration files. You may also analyze various system calls in detail if a broad analysis of your system is required. A very detailed example configuration that includes most of the rules that are needed in a CAPP compliant environment is available in Chapter 33, Introducing an Audit Rule Set.

Audit rules can be passed to the audit daemon on the auditctl command line and by composing a rule set in /etc/audit/audit.rules which is processed whenever the audit daemon is started. To customize /etc/audit/audit.rules either edit it directly, or use YaST: Security and Users › Linux Audit Framework (LAF) › Rules for 'auditctl'. Rules passed on the command line are not persistent and need to be re-entered when the audit daemon is restarted.

A simple rule set for very basic auditing on a few important files and directories could look like this:

# basic audit system parameters
-D
-b 8192
-f 1
-e 1

# some file and directory watches with keys
-w /var/log/audit/ -k LOG_audit
-w /etc/audit/auditd.conf -k CFG_audit_conf -p rxwa
-w /etc/audit/audit.rules -k CFG_audit_rules -p rxwa

-w /etc/passwd -k CFG_passwd -p rwxa
-w /etc/sysconfig/ -k CFG_sysconfig

# an example system call rule
-a entry,always -S umask

### add your own rules

When configuring the basic audit system parameters (such as the backlog parameter -b) test these settings with your intended audit rule set to determine whether the backlog size is appropriate for the level of logging activity caused by your audit rule set. If your chosen backlog size is too small, your system might not be able to handle the audit load and consult the failure flag (-f) when the backlog limit is exceeded.

Important
Important: Choosing the Failure Flag

When choosing the failure flag, note that -f 2 tells your system to perform an immediate shutdown without flushing any pending data to disk when the limits of your audit system are exceeded. Because this shutdown is not a clean shutdown, restrict the use of -f 2 to only the most security-conscious environments and use -f 1 (system continues to run, issues a warning and audit stops) for any other setup to avoid loss of data or data corruption.

Directory watches produce less verbose output than separate file watches for the files under these directories. To get detailed logging for your system configuration in /etc/sysconfig, for example, add watches for each file. Audit does not support globbing, which means you cannot create a rule that says -w /etc/* and watches all files and directories below /etc.

For better identification in the log file, a key has been added to each of the file and directory watches. Using the key, it is easier to comb the logs for events related to a certain rule. When creating keys, distinguish between mere log file watches and configuration file watches by using an appropriate prefix with the key, in this case LOG for a log file watch and CFG for a configuration file watch. Using the file name as part of the key also makes it easier for you to identify events of this type in the log file.

Another thing to keep in mind when creating file and directory watches is that audit cannot deal with files that do not exist when the rules are created. Any file that is added to your system while audit is already running is not watched unless you extend the rule set to watch this new file.

For more information about creating custom rules, refer to Section 31.4, “Passing Parameters to the Audit System”.

Important
Important: Changing Audit Rules

After you change audit rules, always restart the audit daemon with systemctl restart auditd to reread the changed rules.

32.5 Configuring Audit Reports

To avoid having to dig through the raw audit logs to get an impression of what your system is currently doing, run custom audit reports at certain intervals. Custom audit reports enable you to focus on areas of interest and get meaningful statistics on the nature and frequency of the events you are monitoring. To analyze individual events in detail, use the ausearch tool.

Before setting up audit reporting, consider the following:

  • What types of events do you want to monitor by generating regular reports? Select the appropriate aureport command lines as described in Section 31.5.2, “Generating Custom Audit Reports”.

  • What do you want to do with the audit reports? Decide whether to create graphical charts from the data accumulated or whether it should be transferred into any sort of spreadsheet or database. Set up the aureport command line and further processing similar to the examples shown in Section 32.6, “Configuring Log Visualization” if you want to visualize your reports.

  • When and at which intervals should the reports run? Set up appropriate automated reporting using cron.

For this example, assume that you are interested in finding out about any attempts to access your audit, PAM, and system configuration. Proceed as follows to find out about file events on your system:

  1. Generate a full summary report of all events and check for any anomalies in the summary report, for example, have a look at the failed syscalls record, because these might have failed because of insufficient permissions to access a file or a file not being there:

    aureport
    
    Summary Report
    ======================
    Range of time in logs: 03/02/09 14:13:38.225 - 17/02/09 16:30:10.352
    Selected time for report: 03/02/09 14:13:38 - 17/02/09 16:30:10.352
    Number of changes in configuration: 24
    Number of changes to accounts, groups, or roles: 0
    Number of logins: 9
    Number of failed logins: 15
    Number of authentications: 19
    Number of failed authentications: 578
    Number of users: 3
    Number of terminals: 15
    Number of host names: 4
    Number of executables: 20
    Number of files: 279
    Number of AVC's: 0
    Number of MAC events: 0
    Number of failed syscalls: 994
    Number of anomaly events: 0
    Number of responses to anomaly events: 0
    Number of crypto events: 0
    Number of keys: 2
    Number of process IDs: 1238
    Number of events: 5435
  2. Run a summary report for failed events and check the files record for the number of failed file access events:

    aureport --failed
    
    Failed Summary Report
    ======================
    Range of time in logs: 03/02/09 14:13:38.225 - 17/02/09 16:30:10.352
    Selected time for report: 03/02/09 14:13:38 - 17/02/09 16:30:10.352
    Number of changes in configuration: 0
    Number of changes to accounts, groups, or roles: 0
    Number of logins: 0
    Number of failed logins: 15
    Number of authentications: 0
    Number of failed authentications: 578
    Number of users: 1
    Number of terminals: 7
    Number of host names: 4
    Number of executables: 12
    Number of files: 77
    Number of AVC's: 0
    Number of MAC events: 0
    Number of failed syscalls: 994
    Number of anomaly events: 0
    Number of responses to anomaly events: 0
    Number of crypto events: 0
    Number of keys: 2
    Number of process IDs: 713
    Number of events: 1589
  3. To list the files that could not be accessed, run a summary report of failed file events:

    aureport -f -i --failed --summary
    
    Failed File Summary Report
    ===========================
    total  file
    ===========================
    80  /var
    80  spool
    80  cron
    80  lastrun
    46  /usr/lib/locale/en_GB.UTF-8/LC_CTYPE
    45  /usr/lib/locale/locale-archive
    38  /usr/lib/locale/en_GB.UTF-8/LC_IDENTIFICATION
    38  /usr/lib/locale/en_GB.UTF-8/LC_MEASUREMENT
    38  /usr/lib/locale/en_GB.UTF-8/LC_TELEPHONE
    38  /usr/lib/locale/en_GB.UTF-8/LC_ADDRESS
    38  /usr/lib/locale/en_GB.UTF-8/LC_NAME
    38  /usr/lib/locale/en_GB.UTF-8/LC_PAPER
    38  /usr/lib/locale/en_GB.UTF-8/LC_MESSAGES
    38  /usr/lib/locale/en_GB.UTF-8/LC_MONETARY
    38  /usr/lib/locale/en_GB.UTF-8/LC_COLLATE
    38  /usr/lib/locale/en_GB.UTF-8/LC_TIME
    38  /usr/lib/locale/en_GB.UTF-8/LC_NUMERIC
    8  /etc/magic.mgc
    ...

    To focus this summary report on a few files or directories of interest only, such as /etc/audit/auditd.conf, /etc/pam.d, and /etc/sysconfig, use a command similar to the following:

    aureport -f -i --failed --summary |grep -e "/etc/audit/auditd.conf" -e "/etc/pam.d/" -e "/etc/sysconfig"
    
    1  /etc/sysconfig/displaymanager
  4. From the summary report, then proceed to isolate these items of interest from the log and find out their event IDs for further analysis:

    aureport -f -i --failed |grep -e "/etc/audit/auditd.conf" -e "/etc/pam.d/" -e "/etc/sysconfig"
    
    993. 17/02/09 16:47:34 /etc/sysconfig/displaymanager readlink no /bin/vim-normal root 7887
    994. 17/02/09 16:48:23 /etc/sysconfig/displaymanager getxattr no /bin/vim-normal root 7889
  5. Use the event ID to get a detailed record for each item of interest:

    ausearch -a 7887 -i
    ----
    time->Tue Feb 17 16:48:23 2009
    type=PATH msg=audit(1234885703.090:7889): item=0 name="/etc/sysconfig/displaymanager" inode=369282 dev=08:06 mode=0100644 ouid=0 ogid=0 rdev=00:00
    type=CWD msg=audit(1234885703.090:7889):  cwd="/root"
    type=SYSCALL msg=audit(1234885703.090:7889): arch=c000003e syscall=191 success=no exit=-61 a0=7e1e20 a1=7f90e4cf9187 a2=7fffed5b57d0 a3=84 items=1 ppid=25548 pid=23045 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts2 ses=1166 comm="vim" exe="/bin/vim-normal" key=(null)
Tip
Tip: Focusing on a Certain Time Frame

If you are interested in events during a particular period of time, trim down the reports by using start and end dates and times with your aureport commands (-ts and -te). For more information, refer to Section 31.5.2, “Generating Custom Audit Reports”.

All steps (except for the last one) can be run automatically and would easily be scriptable and configured as cron jobs. Any of the --failed --summary reports could be transformed easily into a bar chart that plots files versus failed access attempts. For more information about visualizing audit report data, refer to Section 32.6, “Configuring Log Visualization”.

32.6 Configuring Log Visualization

Using the scripts mkbar and mkgraph you can illustrate your audit statistics with various graphs and charts. As with any other aureport command, the plotting commands are scriptable and can easily be configured to run as cron jobs.

mkbar and mkgraph were created by Steve Grubb at Red Hat. They are available from http://people.redhat.com/sgrubb/audit/visualize/. Because the current version of audit in SUSE Linux Enterprise Server does not ship with these scripts, proceed as follows to make them available on your system:

Warning
Warning: Downloaded Content Is Dangerous

Use mkbar and mkgraph at your own risk. Any content downloaded from the Web is potentially dangerous to your system, even more so when run with root privileges.

  1. Download the scripts to root's ~/bin directory:

    wget http://people.redhat.com/sgrubb/audit/visualize/mkbar -O ~/bin/mkbar
    wget http://people.redhat.com/sgrubb/audit/visualize/mkgraph -O ~/bin/mkgraph
  2. Adjust the file permissions to read, write, and execute for root:

    chmod 744 ~/bin/mk{bar,graph}

To plot summary reports, such as the ones discussed in Section 32.5, “Configuring Audit Reports”, use the script mkbar. Some example commands could look like the following:

Create a Summary of Events
aureport -e -i --summary | mkbar events
Create a Summary of File Events
aureport -f -i --summary | mkbar files
Create a Summary of Login Events
aureport -l -i --summary | mkbar login
Create a Summary of User Events
aureport -u -i --summary | mkbar users
Create a Summary of System Call Events
aureport -s -i --summary | mkbar syscalls

To create a summary chart of failed events of any of the above event types, add the --failed option to the respective aureport command. To cover a certain period of time only, use the -ts and -te options on aureport. Any of these commands can be tweaked further by narrowing down its scope using grep or egrep and regular expressions. See the comments in the mkbar script for an example. Any of the above commands produces a PNG file containing a bar chart of the requested data.

To illustrate the relationship between different kinds of audit objects, such as users and system calls, use the script mkgraph. Some example commands could look like the following:

Users versus Executables
LC_ALL=C aureport -u -i | awk '/^[0-9]/ { print $4" "$7 }' | sort | uniq | mkgraph users_vs_exec
Users versus Files
LC_ALL=C aureport -f -i | awk '/^[0-9]/ { print $8" "$4 }' | sort | uniq | mkgraph users_vs_files
System Calls versus Commands
LC_ALL=C aureport -s -i | awk '/^[0-9]/ { print $4" "$6 }' | sort | uniq | mkgraph syscall_vs_com
System Calls versus Files
LC_ALL=C aureport -s -i | awk '/^[0-9]/ { print $5" "$4 }' | sort | uniq | mkgraph | syscall_vs_file

Graphs can also be combined to illustrate complex relationships. See the comments in the mkgraph script for further information and an example. The graphs produced by this script are created in PostScript format by default, but you can change the output format by changing the EXT variable in the script from ps to png or jpg.

33 Introducing an Audit Rule Set

  • Filename: audit_scenarios.xml
  • ID: cha.audit.scenarios

The following example configuration illustrates how audit can be used to monitor your system. It highlights the most important items that need to be audited to cover the list of auditable events specified by Controlled Access Protection Profile (CAPP).

The example rule set is divided into the following sections:

To transform this example into a configuration file to use in your live setup, proceed as follows:

  1. Choose the appropriate settings for your setup and adjust them.

  2. Adjust the file /etc/audit/audit.rules by adding rules from the examples below or by modifying existing rules.

Note
Note: Adjusting the Level of Audit Logging

Do not copy the example below into your audit setup without adjusting it to your needs. Determine what and to what extent to audit.

The entire audit.rules is a collection of auditctl commands. Every line in this file expands to a full auditctl command line. The syntax used in the rule set is the same as that of the auditctl command.

33.1 Adding Basic Audit Configuration Parameters

-D1
-b 81922
-f 23

1

Delete any preexisting rules before starting to define new ones.

2

Set the number of buffers to take the audit messages. Depending on the level of audit logging on your system, increase or decrease this figure.

3

Set the failure flag to use when the kernel needs to handle critical errors. Possible values are 0 (silent), 1 (printk, print a failure message), and 2 (panic, halt the system).

By emptying the rule queue with the -D option, you make sure that audit does not use any other rule set than what you are offering it by means of this file. Choosing an appropriate buffer number (-b) is vital to avoid having your system fail because of too high an audit load. Choosing the panic failure flag -f 2 ensures that your audit records are complete even if the system is encountering critical errors. By shutting down the system on a critical error, audit makes sure that no process escapes from its control as it otherwise might if level 1 (printk) were chosen.

Important
Important: Choosing the Failure Flag

Before using your audit rule set on a live system, make sure that the setup has been thoroughly evaluated on test systems using the worst case production workload. It is even more critical that you do this when specifying the -f 2 flag, because this instructs the kernel to panic (perform an immediate halt without flushing pending data to disk) if any thresholds are exceeded. Consider the use of the -f 2 flag for only the most security-conscious environments.

33.2 Adding Watches on Audit Log Files and Configuration Files

Adding watches on your audit configuration files and the log files themselves ensures that you can track any attempt to tamper with the configuration files or detect any attempted accesses to the log files.

Note
Note: Creating Directory and File Watches

Creating watches on a directory is not necessarily sufficient if you need events for file access. Events on directory access are only triggered when the directory's inode is updated with metadata changes. To trigger events on file access, add watches for each file to monitor.

-w /var/log/audit/ 1
-w /var/log/audit/audit.log

-w /var/log/audit/audit_log.1
-w /var/log/audit/audit_log.2
-w /var/log/audit/audit_log.3
-w /var/log/audit/audit_log.4

-w /etc/audit/auditd.conf -p wa2
-w /etc/audit/audit.rules -p wa
-w /etc/libaudit.conf -p wa

1

Set a watch on the directory where the audit log is located. Trigger an event for any type of access attempt to this directory. If you are using log rotation, add watches for the rotated logs as well.

2

Set a watch on an audit configuration file. Log all write and attribute change attempts to this file.

33.3 Monitoring File System Objects

Auditing system calls helps track your system's activity well beyond the application level. By tracking file system–related system calls, get an idea of how your applications are using these system calls and determine whether that use is appropriate. By tracking mount and unmount operations, track the use of external resources (removable media, remote file systems, etc.).

Important
Important: Auditing System Calls

Auditing system calls results in a high logging activity. This activity, in turn, puts a heavy load on the kernel. With a kernel less responsive than usual, the system's backlog and rate limits might be exceeded. Carefully evaluate which system calls to include in your audit rule set and adjust the log settings accordingly. See Section 31.2, “Configuring the Audit Daemon” for details on how to tweak the relevant settings.

-a entry,always -S chmod -S fchmod -S chown -S chown32 -S fchown -S fchown32 -S lchown -S lchown321

-a entry,always -S creat -S open -S truncate -S truncate64 -S ftruncate -S ftruncate642

-a entry,always -S mkdir -S rmdir3

-a entry,always -S unlink -S rename -S link -S symlink4

-a entry,always -S setxattr5
-a entry,always -S lsetxattr
-a entry,always -S fsetxattr
-a entry,always -S removexattr
-a entry,always -S lremovexattr
-a entry,always -S fremovexattr

-a entry,always -S mknod6

-a entry,always -S mount -S umount -S umount27

1

Enable an audit context for system calls related to changing file ownership and permissions. Depending on the hardware architecture of your system, enable or disable the *32 rules. 64-bit systems, like AMD64/Intel 64, require the *32 rules to be removed.

2

Enable an audit context for system calls related to file content modification. Depending on the hardware architecture of your system, enable or disable the *64 rules. 64-bit systems, like AMD64/Intel 64, require the *64 rules to be removed.

3

Enable an audit context for any directory operation, like creating or removing a directory.

4

Enable an audit context for any linking operation, such as creating a symbolic link, creating a link, unlinking, or renaming.

5

Enable an audit context for any operation related to extended file system attributes.

6

Enable an audit context for the mknod system call, which creates special (device) files.

7

Enable an audit context for any mount or umount operation. For the x86 architecture, disable the umount rule. For the Intel 64 architecture, disable the umount2 rule.

33.4 Monitoring Security Configuration Files and Databases

To make sure that your system is not made to do undesired things, track any attempts to change the cron and at configurations or the lists of scheduled jobs. Tracking any write access to the user, group, password and login databases and logs helps you identify any attempts to manipulate your system's user database.

Tracking changes to your system configuration (kernel, services, time, etc.) helps you spot any attempts of others to manipulate essential functionality of your system. Changes to the PAM configuration should also be monitored in a secure environment, because changes in the authentication stack should not be made by anyone other than the administrator, and it should be logged which applications are using PAM and how it is used. The same applies to any other configuration files related to secure authentication and communication.

1
-w /var/spool/atspool
-w /etc/at.allow
-w /etc/at.deny

-w /etc/cron.allow -p wa
-w /etc/cron.deny -p wa
-w /etc/cron.d/ -p wa
-w /etc/cron.daily/ -p wa
-w /etc/cron.hourly/ -p wa
-w /etc/cron.monthly/ -p wa
-w /etc/cron.weekly/ -p wa
-w /etc/crontab -p wa
-w /var/spool/cron/root

2
-w /etc/group -p wa
-w /etc/passwd -p wa
-w /etc/shadow

-w /etc/login.defs -p wa
-w /etc/securetty
-w /var/log/lastlog

3
-w /etc/hosts -p wa
-w /etc/sysconfig/
w /etc/init.d/
w /etc/ld.so.conf -p wa
w /etc/localtime -p wa
w /etc/sysctl.conf -p wa
w /etc/modprobe.d/
w /etc/modprobe.conf.local -p wa
w /etc/modprobe.conf -p wa
4
w /etc/pam.d/
5
-w /etc/aliases -p wa
-w /etc/postfix/ -p wa

6
-w /etc/ssh/sshd_config

-w /etc/stunnel/stunnel.conf
-w /etc/stunnel/stunnel.pem

-w /etc/vsftpd.ftpusers
-w /etc/vsftpd.conf

7
-a exit,always -S sethostname
-w /etc/issue -p wa
-w /etc/issue.net -p wa

1

Set watches on the at and cron configuration and the scheduled jobs and assign labels to these events.

2

Set watches on the user, group, password, and login databases and logs and set labels to better identify any login-related events, such as failed login attempts.

3

Set a watch and a label on the static host name configuration in /etc/hosts. Track changes to the system configuration directory, /etc/sysconfig. Enable per-file watches if you are interested in file events. Set watches and labels for changes to the boot configuration in the /etc/init.d directory. Enable per-file watches if you are interested in file events. Set watches and labels for any changes to the linker configuration in /etc/ld.so.conf. Set watches and a label for /etc/localtime. Set watches and labels for the kernel configuration files /etc/sysctl.conf, /etc/modprobe.d/, /etc/modprobe.conf.local, and /etc/modprobe.conf.

4

Set watches on the PAM configuration directory. If you are interested in particular files below the directory level, add explicit watches to these files as well.

5

Set watches to the postfix configuration to log any write attempt or attribute change and use labels for better tracking in the logs.

6

Set watches and labels on the SSH, stunnel, and vsftpd configuration files.

7

Perform an audit of the sethostname system call and set watches and labels on the system identification configuration in /etc/issue and /etc/issue.net.

33.5 Monitoring Miscellaneous System Calls

Apart from auditing file system related system calls, as described in Section 33.3, “Monitoring File System Objects”, you can also track various other system calls. Tracking task creation helps you understand your applications' behavior. Auditing the umask system call lets you track how processes modify creation mask. Tracking any attempts to change the system time helps you identify anyone or any process trying to manipulate the system time.

1
-a entry,always -S clone -S fork -S vfork

2
-a entry,always -S umask

3
-a entry,always -S adjtimex -S settimeofday

1

Track task creation.

2

Add an audit context to the umask system call.

3

Track attempts to change the system time. adjtimex can be used to skew the time. settimeofday sets the absolute time.

33.6 Filtering System Call Arguments

In addition to the system call auditing introduced in Section 33.3, “Monitoring File System Objects” and Section 33.5, “Monitoring Miscellaneous System Calls”, you can track application behavior to an even higher degree. Applying filters helps you focus audit on areas of primary interest to you. This section introduces filtering system call arguments for non-multiplexed system calls like access and for multiplexed ones like socketcall or ipc. Whether system calls are multiplexed depends on the hardware architecture used. Both socketcall and ipc are not multiplexed on 64-bit architectures, such as AMD64/Intel 64.

Important
Important: Auditing System Calls

Auditing system calls results in high logging activity, which in turn puts a heavy load on the kernel. With a kernel less responsive than usual, the system's backlog and rate limits might well be exceeded. Carefully evaluate which system calls to include in your audit rule set and adjust the log settings accordingly. See Section 31.2, “Configuring the Audit Daemon” for details on how to tweak the relevant settings.

The access system call checks whether a process would be allowed to read, write or test for the existence of a file or file system object. Using the -F filter flag, build rules matching specific access calls in the format-F a1=ACCESS_MODE. Check /usr/include/fcntl.h for a list of possible arguments to the access system call.

-a entry,always -S access -F a1=41
-a entry,always -S access -F a1=62
-a entry,always -S access -F a1=73

1

Audit the access system call, but only if the second argument of the system call (mode) is 4 (R_OK). This rule filters for all access calls testing for sufficient read permissions to a file or file system object accessed by a user or process.

2

Audit the access system call, but only if the second argument of the system call (mode) is 6, meaning 4 OR 2, which translates to R_OK OR W_OK. This rule filters for access calls testing for sufficient read and write permissions.

3

Audit the access system call, but only if the second argument of the system call (mode) is 7, meaning 4 OR 2 OR 1, which translates to R_OK OR W_OK OR X_OK. This rule filters for access calls testing for sufficient read, write, and execute permissions.

The socketcall system call is a multiplexed system call. Multiplexed means that there is only one system call for all possible calls and that libc passes the actual system call to use as the first argument (a0). Check the manual page of socketcall for possible system calls and refer to /usr/src/linux/include/linux/net.h for a list of possible argument values and system call names. Audit supports filtering for specific system calls using a -F a0=SYSCALL_NUMBER.

-a entry,always -S socketcall -F a0=1 -F a1=101
## Use this line on x86_64, ia64 instead
#-a entry,always -S socket -F a0=10

-a entry,always -S socketcall -F a0=52
## Use this line on x86_64, ia64 instead
#-a entry, always -S accept

1

Audit the socket(PF_INET6) system call. The -F a0=1 filter matches all socket system calls and the -F a1=10 filter narrows the matches down to socket system calls carrying the IPv6 protocol family domain parameter (PF_INET6). Check /usr/include/linux/net.h for the first argument (a0) and /usr/src/linux/include/linux/socket.h for the second parameter (a1). 64-bit platforms, like AMD64/Intel 64, do not use multiplexing on socketcall system calls. For these platforms, comment the rule and add the plain system call rules with a filter on PF_INET6.

2

Audit the socketcall system call. The filter flag is set to filter for a0=5 as the first argument to socketcall, which translates to the accept system call if you check /usr/include/linux/net.h. 64-bit platforms, like AMD64/Intel 64, do not use multiplexing on socketcall system calls. For these platforms, comment the rule and add the plain system call rule without argument filtering.

The ipc system call is another example of multiplexed system calls. The actual call to invoke is determined by the first argument passed to the ipc system call. Filtering for these arguments helps you focus on those IPC calls of interest to you. Check /usr/include/linux/ipc.h for possible argument values.

1
## msgctl
-a entry,always -S ipc -F a0=14
## msgget
-a entry,always -S ipc -F a0=13
## Use these lines on x86_64, ia64 instead
#-a entry,always -S msgctl
#-a entry,always -S msgget

2
## semctl
-a entry,always -S ipc -F a0=3
## semget
-a entry,always -S ipc -F a0=2
## semop
-a entry,always -S ipc -F a0=1
## semtimedop
-a entry,always -S ipc -F a0=4
## Use these lines on x86_64, ia64 instead
#-a entry,always -S semctl
#-a entry,always -S semget
#-a entry,always -S semop
#-a entry,always -S semtimedop

3
## shmctl
-a entry,always -S ipc -F a0=24
## shmget
-a entry,always -S ipc -F a0=23
## Use these lines on x86_64, ia64 instead
#-a entry,always -S shmctl
#-a entry,always -S shmget

1

Audit system calls related to IPC SYSV message queues. In this case, the a0 values specify that auditing is added for the msgctl and msgget system calls (14 and 13). 64-bit platforms, like AMD64/Intel 64, do not use multiplexing on ipc system calls. For these platforms, comment the first two rules and add the plain system call rules without argument filtering.

2

Audit system calls related to IPC SYSV message semaphores. In this case, the a0 values specify that auditing is added for the semctl, semget, semop, and semtimedop system calls (3, 2, 1, and 4). 64-bit platforms, like AMD64/Intel 64, do not use multiplexing on ipc system calls. For these platforms, comment the first four rules and add the plain system call rules without argument filtering.

3

Audit system calls related to IPC SYSV shared memory. In this case, the a0 values specify that auditing is added for the shmctl and shmget system calls (24, 23). 64-bit platforms, like AMD64/Intel 64, do not use multiplexing on ipc system calls. For these platforms, comment the first two rules and add the plain system call rules without argument filtering.

33.7 Managing Audit Event Records Using Keys

After configuring a few rules generating events and populating the logs, you need to find a way to tell one event from the other. Using the ausearch command, you can filter the logs for various criteria. Using ausearch -m MESSAGE_TYPE, you can at least filter for events of a certain type. However, to be able to filter for events related to a particular rule, you need to add a key to this rule in the /etc/audit/audit.rules file. This key is then added to the event record every time the rule logs an event. To retrieve these log entries, simply run ausearch -k YOUR_KEY to get a list of records related to the rule carrying this particular key.

As an example, assume you have added the following rule to your rule file:

-w /etc/audit/audit.rules -p wa

Without a key assigned to it, you would probably need to filter for SYSCALL or PATH events then use grep or similar tools to isolate any events related to the above rule. Now, add a key to the above rule, using the -k option:

-w /etc/audit/audit.rules -p wa -k CFG_audit.rules

You can specify any text string as key. Distinguish watches related to different types of files (configuration files or log files) from one another using different key prefixes (CFG, LOG, etc.) followed by the file name. Finding any records related to the above rule now comes down to the following:

ausearch -k CFG_audit.rules
----
time->Thu Feb 19 09:09:54 2009
type=PATH msg=audit(1235030994.032:8649): item=3 name="audit.rules~" inode=370603 dev=08:06 mode=0100640 ouid=0 ogid=0 rdev=00:00
type=PATH msg=audit(1235030994.032:8649): item=2 name="audit.rules" inode=370603 dev=08:06 mode=0100640 ouid=0 ogid=0 rdev=00:00
type=PATH msg=audit(1235030994.032:8649): item=1  name="/etc/audit" inode=368599 dev=08:06 mode=040750 ouid=0 ogid=0 rdev=00:00
type=PATH msg=audit(1235030994.032:8649): item=0  name="/etc/audit" inode=368599 dev=08:06 mode=040750 ouid=0 ogid=0 rdev=00:00
type=CWD msg=audit(1235030994.032:8649):  cwd="/etc/audit"
type=SYSCALL msg=audit(1235030994.032:8649): arch=c000003e syscall=82 success=yes exit=0 a0=7deeb0 a1=883b30 a2=2 a3=ffffffffffffffff items=4 ppid=25400 pid=32619 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts1 ses=1164 comm="vim" exe="/bin/vim-normal" key="CFG_audit.rules"

34 Useful Resources

  • Filename: audit_moreinfo.xml
  • ID: cha.audit.moreinfo

There are other resources available containing valuable information about the Linux audit framework:

The Audit Manual Pages

There are several man pages installed along with the audit tools that provide valuable and very detailed information:

auditd(8)

The Linux audit daemon

auditd.conf(5)

The Linux audit daemon configuration file

auditctl(8)

A utility to assist controlling the kernel's audit system

autrace(8)

A program similar to strace

ausearch(8)

A tool to query audit daemon logs

aureport(8)

A tool that produces summary reports of audit daemon logs

audispd.conf(5)

The audit event dispatcher configuration file

audispd(8)

The audit event dispatcher daemon talking to plug-in programs.

http://people.redhat.com/sgrubb/audit/index.html

The home page of the Linux audit project. This site contains several specifications relating to different aspects of Linux audit, and a short FAQ.

/usr/share/doc/packages/audit

The audit package itself contains a README with basic design information and sample .rules files for different scenarios:

capp.rules: Controlled Access Protection Profile (CAPP)
lspp.rules: Labeled Security Protection Profile (LSPP)
nispom.rules: National Industrial Security Program Operating Manual Chapter 8(NISPOM)
stig.rules: Secure Technical Implementation Guide (STIG)
http://www.commoncriteriaportal.org/

The official Web site of the Common Criteria project. Learn all about the Common Criteria security certification initiative and which role audit plays in this framework.

A Achieving PCI-DSS Compliance

  • Filename: security_pcidss.xml
  • ID: app.pcidss
Abstract

To protect customers and the business itself, companies that handle credit card payments must keep data as safe and secure as possible. Following the Payment Card Industry Data Security Standard helps to secure all areas that are connected to payment processes and to implement security-relevant actions to keep the data and the computing environment safe.

This document aims to provide a basic understanding of how SUSE Linux Enterprise Server can be configured to comply with the Payment Card Industry Data Security Standard.

It is important to understand that protecting systems includes more than configuration. The entire environment and people involved must be taken into account.

An essential part of implementing PCI-DSS is the combination of actions:

  1. Create a secure configuration.

  2. Track and review all changes made to the configuration: who changed what at which point in time.

A.1 What is the PCI-DSS?

The Payment Card Industry Data Security Standard (PCI-DSS) is a set of requirements to guide a merchant to protect cardholder data. The standard covers 6 main categories with currently 12 requirement topics how to implement, protect, maintain and monitor systems that are involved with credit cardholder data processing.

PCI-DSS was created and is maintained by the PCI Security Standards Council (SSC) that was founded by all five major credit card brands Visa, MasterCard, American Express, Discover, and JCB. In December 2004, PCI-DSS 1.0 was released to address the growing thread of online credit card fraud. The current version, PCI-DSS version 3.2 has been available since April 2016.

Build and Maintain a Secure Network and Systems
  1. Install and maintain a firewall configuration to protect cardholder data

  2. Do not use vendor-supplied defaults for system passwords and other security parameters

Protect Cardholder Data
  1. Protect stored cardholder data

  2. Encrypt transmission of cardholder data across open, public networks

Maintain a Vulnerability Management Program
  1. Protect all systems against malware and regularly update anti-virus software or programs

  2. Develop and maintain secure systems and applications

Implement Strong Access Control Measures
  1. Restrict access to cardholder data by business need to know

  2. Identify and authenticate access to system components

  3. Restrict physical access to cardholder data

Regularly Monitor and Test Networks
  1. Track and monitor all access to network resources and cardholder data

  2. Regularly test security systems and processes

Maintain an Information Security Policy
  1. Maintain a policy that addresses information security for all personnel

Most requirements of PCI-DSS are organizational guidelines that help ensure the security of all areas involved with cardholder data. There is usually no specific wording of technical aspects.

This means that it is up to auditors to decide which security settings are valid for a requirement and which are not. Therefore, the recommendations in this document can only provide a starting point for implementing the PCI-DSS and are necessarily subject to discussion.

A.2 Focus of This Document: Areas Relevant to the Operating System

The PCI-DSS covers a wide range of aspects related to cardholder data. Not all of these aspects concern the operating system and this document will not focus on these. Instead, this document focuses on aspects that affect OS configuration, including:

  • System security

  • Access control

  • System maintenance to protect against known vulnerabilities

Topics beyond the scope of this document include data processing applications, database design, and formal processes outside of the OS scope. In particular, requirement 9 (restrict physical access) and requirement 12 (maintain a policy) are not discussed extensively in this document.

A.3 Requirements in Detail

The following section goes through relevant parts of the PCI-DSS in detail, following the ordering of the standard itself.

A.3.1 Requirement 1: Install and Maintain a Firewall Configuration to Protect Cardholder Data

The listed terms in this section are mostly design, documentation and formal process requirements. All changes to the firewalls and routers need to be approved, documented and verified, and all stakeholders need to be involved. The network design includes a DMZ environment, access to the Internet, a protected network for database servers, traffic filtering rules between network segments etc.

In addition to a dedicated firewall and router, SUSE Linux Enterprise Server comes with a host firewall based on iptables. The system can be easily configured to allow only connections on certain inbound ports. With the YaST firewall module it is also possible to define more complex rules. For example, to disable connections not coming from certain network addresses. This allows integrating the local system firewall into an overall firewall design that maximizes network security.

In generalized terms, the technical points in requirement 1 are the following:

  • Identify insecure services and protocols.

  • Limit traffic to and from the system so that unneeded and unwanted traffic is directly avoided.

1.1.6.b Identify insecure services, protocols, and ports allowed; and verify that security features are documented for each service.

This task is embedded into the requirement to identify, document and justify all services and protocols running on a system. A special interest are services and protocols that could lead to a security risk. If an insecure service or protocol is used, it must be evaluated to understood its potential security impact. Services or protocols that are not necessary for the business to function should be disabled or removed.

1.2.1.b Examine firewall and router configurations to verify that inbound and outbound traffic is limited to that which is necessary for the cardholder data environment.

Inbound traffic filtering rules can be defined from the YaST firewall module. Systems with multiple interfaces can be configured to make the SSH daemon only reachable on the administration interface and not on the general network card. Furthermore, it is possible to define the source addresses that a service allows traffic from.

Usually all outbound system traffic is allowed by the SuSEFirewall2 script. Therefore outbound rules need to be defined manually inside the SuSEFirewall2 custom script. Activate the custom script inside the general SuSEFirewall2 configuration file /etc/sysconfig/SuSEfirewall2 by uncommenting the FW_CUSTOMRULES line.

To add an outbound rule, add an appropriate iptables command line inside the fw_custom_after_chain_creation() function. This function hook is executed during the firewall setup and allows any customized iptables rule.

For example, to allow only outbound DNS requests over the interface eth0 to server 10.0.0.4, use:

tux > sudo iptables -A OUTPUT -d 10.0.0.4/32 -o eth0 -p udp -m udp --dport 53 -j ACCEPT

Also see the deny all OUTPUT rule described in 1.2.1.c Examine firewall and router configurations to verify that all other inbound and outbound traffic is specifically denied, for example by using an explicit deny all or an implicit deny after allow statement. .

1.2.1.c Examine firewall and router configurations to verify that all other inbound and outbound traffic is specifically denied, for example by using an explicit deny all or an implicit deny after allow statement.

The deny all rules of other inbound and outbound traffic can easily be achieved with iptables. The INPUT and FORWARD table policies are directly set by the SuSEFirewall2 script, so all unwanted traffic is dropped. Forwarding is usually completely disabled by a kernel parameter and should not be enabled for endpoint servers.

The OUTPUT policy needs to be defined manually inside the custom SuSEFirewall2 script because in general, all outgoing traffic is allowed. The following two rules need to be added to the fw_custom_after_chain_creation() function so that only outbound traffic that is related to an established inbound connection is allowed.

tux > sudo iptables -A OUTPUT -m conntrack --ctstate ESTABLISHED -j ACCEPT
tux > sudo iptables -P OUTPUT DROP

In addition, inbound traffic can also be configured for certain services via the tcp wrapper configuration file /etc/hosts.deny.

Most of the following tasks are about examine and verifying that the defined inbound and outbound rules are really limiting the traffic between and within all network segments, like the DMZ and the Internet, to a needed minimum for full system operation.

1.3.3 Implement anti-spoofing measures to detect and block forged source IP addresses from entering the network.

There are two ways to implement anti-spoofing measurements in SUSE Linux Enterprise Server:

  • iptables rules that only allow input from certain addresses on specified interfaces.  The used address space for communications can be clearly defined in the system setup. Any use of addresses that violate these definitions can be logged and trigger an alarm.

  • Linux Kernel Reverse Path Filtering.  This feature discards packet replies that do not go through the same interface as the initial packet. This feature is enabled by default in SUSE Linux Enterprise Server and can be checked with the following command:

    tux > cat /proc/sys/net/ipv4/conf/all/rp_filter

    When enabled, this returns 1.

1.3.5 Permit only established connections into the network.

The SuSEFirewall2 enables connection tracking via iptables. Connections to an interface that has been marked as external are dropped by default. Only connections that associated with an established connection are allowed.

It is possible to define certain services that are allowed to connect to the external interface. However, this must be in compliance with the general security policy.

Keep in mind that the first line of defense against malicious connections from the Internet should be a dedicated firewall system that handles all traffic and acts as a gate keeper. Unwanted connections should never reach the DMZ network. However, simple firewall rules on SUSE Linux Enterprise Server systems can help avoid misconfigurations and act as another line of defense.

1.3.7 Do not disclose private IP addresses and routing information to unauthorized parties.

A SUSE Linux Enterprise Server system can also act as a router to forward traffic from one interface to another network on a second interface. It is possible to use Network Address Translation (NAT) on the external interface so that no internal IP address is actually exposed to outside. This is done to mitigate the information an external attacker can gather by simply analyzing the network traffic. NAT can also be used on virtualization hosts or container-based environments that connect to the outside via a specific interface.

A.3.2 Requirement 2: Do Not Use Vendor-Supplied Defaults for System Passwords and Other Security Parameters

During the installation of SUSE Linux Enterprise Server, general system passwords are already set by the administrator. The setup also uses a password checker (cracklib) that identifies weak entries against a dictionary. This means that the standard configuration already includes customer-defined security options for most services.

For more information about OS security, see Security Guide and Security and Hardening Guide.

2.1 Always change vendor-supplied defaults and remove or disable unnecessary default accounts before installing a system on the network.

The configuration of any system service must be evaluated to meet the needed security standards. This goes from limiting the used protocols to only allow currently secure versions and to disable legacy implementations, to the definition of access controls and authentication. The default settings of SUSE Linux Enterprise Server already provide good overall security, but they can be tweaked further.

For example, the following security settings might be relevant:

  • By default, the SNMP daemon only allows incoming requests to localhost. However, the default community string is named public and should be changed before accepting general inbound connections.

  • By default, certain insecure upstream settings of the sshd daemon are listed and commented out inside the sshd configuration file /etc/ssh/sshd_config. For example, the insecure protocol version 1 and empty passwords (PermitEmptyPasswords no) are already disabled.

    To further increase SSH security, if applicable, deny direct root access by setting PermitRootLogin to no.

Default settings can be customized by automating system installation with an AutoYaST profile. This allows rolling out new instances of SUSE Linux Enterprise Server and automatically enabling an evaluated configuration. This setup procedure can also be automated with the SUSE Manager. For more information, see the SUSE Manager documentation at https://www.suse.com/documentation/suse-manager.

By default, SUSE Linux Enterprise Server does not create additional accounts apart from the root administrative user. There are system accounts defined in /etc/passwd, but they are not activated and therefore not directly reachable. This can be validated by checking the lines inside the /etc/shadow file.

In that file, the second column represents the defined password:

  • An asterisk (*) means that a password was never defined and the account is therefore locked.

  • An exclamation mark (!) stands for a locked account and can stand all by itself or in front of a password hash.

2.2 Develop configuration standards for all system components. Assure that these standards address all known security vulnerabilities and are consistent with industry-accepted system hardening standards.

As mentioned inside the PCI-DSS document, possible sources for industry-accepted hardening standards are:

  1. Center for Internet Security (CIS)

  2. International Organization for Standardization (ISO)

  3. SysAdmin Audit Network Security (SANS) Institute

  4. National Institute of Standards Technology (NIST)

As the PCI-DSS requirements are not specified precisely, there is no direct relationship between hardening standards and specific requirements. However, other hardening resources can also help in complying with these specifications, including Security Guide and Security and Hardening Guide.

2.2.1 Implement only one primary function per server to prevent functions that require different security levels from co-existing on the same server. (For example, web servers, database servers, and DNS should be implemented on separate servers.)

To help separate services, use the variety of virtualization and containerization methods included with SUSE Linux Enterprise Server: KVM, Xen, LXC, and Docker.

You can also run SUSE Linux Enterprise Server on third-party virtualization servers like VMware ESX or Microsoft Hyper-V to achieve service separation.

When using the options built in to SUSE Linux Enterprise Server, see:

2.2.2 Enable only necessary services, protocols, daemons, etc., as required for the function of the system.

This is directly related to an item of requirement 1: To allow only services that are really needed and are using secure protocols and settings ( 1.1.6.b Identify insecure services, protocols, and ports allowed; and verify that security features are documented for each service. ). All parties involved must be aware of the dangers of using insecure communication. Research, clearly document and communicate the risk of using insecure protocols and services.

Enable and disable system services using the following systemctl commands:

  • tux > systemctl status SERVICE
  • tux > sudo systemctl enable SERVICE
  • tux > sudo systemctl disable SERVICE

To list all available services that are installed on the system and see their status, use the following command:

tux > systemctl list-unit-files --type=service
2.2.3.a Inspect configuration settings to verify that security features are documented and implemented for all insecure services, daemons, or protocols.

To add an additional layer of security to insecure services, use VPN tunnels (for example, IPsec). With a VPN tunnel, network traffic of such services can be isolated and all data is protected against eavesdropping, both internally and externally. However, note that the communication is still insecure at the endpoints of the VPN tunnel and that this is only a workaround.

For additional security within SUSE Linux Enterprise Server, use SELinux or AppArmor. However, the setup of these frameworks is beyond the scope of this document:

2.2.5.a Select a sample of system components and inspect the configurations to verify that all unnecessary functionality (for example, scripts, drivers, features, subsystems, file systems, etc.) is removed.

The Linux kernel is the main system component. It consists of a core image that is extended by kernel modules which are loaded depending on the hardware and system design. For example: Network card drivers are automatically loaded depending on the system’s network card. File system modules can be enabled to extend the Linux kernel’s file system support.

The list of loaded kernel modules is usually quite long and includes modules that are only used occasionally. The kernel module framework allows blacklisting modules and limiting which functionality is loaded.

To block modules from being loaded, configure them via the directory /etc/modprobe.d. For example, the kernel module floppy is only necessary for systems that have a floppy drive. On systems that do not have a floppy drive, prevent the module from loading: Create a configuration file /etc/modprobe.d/00-disable-modules.conf with the following content:

install floppy /bin/true

The floppy module is usually loaded during the execution of the initial RAM disk. Therefore, propagate this configuration change to the initrd file using the mkinitrd script.

tux > sudo mkinitrd

It is harder to remove or restrict application functionality, as functionality is in most cases compiled into the application or library itself. Even cases where deleting a file cleanly removes a functionality are problematic: If the file was installed from an RPM package, it will be reinstalled when the package is updated.

2.3 Encrypt all non-console administrative access using strong cryptography. Use technologies such as SSH, VPN, or TLS for web-based management and other non-console administrative access.

Encrypt all administrative network access: SSH with appropriate configuration settings that fit into the security concept should be the tool of choice.

Administrative access can also be granted via a Web site. In this case, the complete connection chain between the browser and the server system must be encrypted. This is done via TLS and X.509 certificates.

A.3.3 Requirement 3: Protect Stored Cardholder Data

The section explains how to handle cardholder and authentication data securely. The following definitions apply:

  • Cardholder data includes information such as the cardholder name and the Primary Account Number (PAN).

  • Authentication data includes the Personal Identification Number (PIN) and the Card Validation Code (CVC2).

The main difference between cardholder data and authentication data is that storing authentication is never allowed. In contrast, data such as the PAN can be stored, but must be encrypted and unreadable in case an attacker gains access to the stored data.

The database design for storing cardholder data is beyond the scope of this document. However, data can be encrypted in different ways:

  • The DBMS can use column-level encryption inside the database scheme.

  • Alternatively, the database files can be encrypted.

  • SUSE Linux Enterprise Server supports full-disk encryption, so that the whole database storage is always encrypted. However, access to an encrypted disk works the same way as to a non-encrypted disk. This is discussed in more detail in requirement 3.4.1.

3.4.1.a If disk encryption is used, inspect the configuration and observe the authentication process to verify that logical access to encrypted file systems is implemented via a mechanism that is separate from the native operating system’s authentication mechanism (for example, not using local user account databases or general network login credentials).

The guidance description of the PCI-DSS document says the following about this requirement: Full disk encryption helps to protect data in the event of physical loss of a disk and therefore may be appropriate for portable devices that store cardholder data.

From an administrator’s point of view, a block device encryption with the Linux Unified Key Setup (LUKS)/dm-crypt offers an abstraction layer that allows the usage of encrypted disks in the same way as unencrypted disks.

Therefore, access control can only be limited with the general ACL permissions that the file system offers. To comply with this requirement, the decryption key used must not be associated with any general login credentials or authentication methods.

When using LUKS, this is usually fulfilled: The password needs to be entered separately when booting, inserting portable devices or manually mounting disks.

LUKS in fully integrated into SUSE Linux Enterprise Server and can be used via YaST to create new partitions.

3.4.1.c Examine the configurations and observe the processes to verify that cardholder data on removable media is encrypted wherever stored.

As described in 3.4.1.a If disk encryption is used, inspect the configuration and observe the authentication process to verify that logical access to encrypted file systems is implemented via a mechanism that is separate from the native operating system’s authentication mechanism (for example, not using local user account databases or general network login credentials). , LUKS/dm-crypt provides full-disk encryption that fulfills this requirement. Access to the stored data is only possible via a decryption password that must be entered when the disk is mounted.

A.3.4 Requirement 4: Encrypt Transmission of Cardholder Data Across Open, Public Networks

Cardholder data must be encrypted during transmissions over insecure networks. Ideally, encrypt all traffic, externally and internally. This makes it hard for attackers to gain inside information and privileged access to the cardholder data environment.

4.1 Use strong cryptography and security protocols (for example, TLS, IPSEC, SSH, etc.) to safeguard sensitive cardholder data during transmission over open, public networks, including the following: (1) Only trusted keys and certificates are accepted, (2) The protocol in use only supports secure versions or configurations, (3) The encryption strength is appropriate for the encryption methodology in use.

Any connection that transmits sensitive information must be protected against eavesdropping and tampering.

For incoming client requests, use the HTTPS protocol with a secure TLS connection. The authentication is done with a public X.509 certificate that proves to a certain level that the server is the right endpoint the customer is looking for.

SUSE Linux Enterprise Server comes with a set of services and tools that allow protected HTTPS connections. For example, this can be directly done with the Apache HTTP Server or via stunnel that functions as a proxy to offer TLS encryption functionality.

IPsec or other VPN technologies can be used for securing the connection between network segments that are connected via a public network. Such connections can also be secured with a public X.509 certificate. For internal usage, it is possible to use a private Certificate Authority (CA) to sign X.509 certificates and to keep track of trusted keys.

In SUSE Linux Enterprise Server, this can be directly established with strongSwan that is a IPsec-based VPN solution or with OpenVPN that is using a custom security protocol.

To administrate the OS, use SSH. For information about configuring SSH to provide better security, see Section A.3.1, “Requirement 1: Install and Maintain a Firewall Configuration to Protect Cardholder Data” and Section A.3.2, “Requirement 2: Do Not Use Vendor-Supplied Defaults for System Passwords and Other Security Parameters”.

A.3.5 Requirement 5: Protect All Systems Against Malware and Regularly Update Anti-Virus Software or Programs

For PCI-DSS compliance, it is necessary to protect against malicious software. Third-party anti-virus software is available from the major anti-virus software vendors and can be integrated into the Linux environment. SUSE Linux Enterprise Server comes with the open source anti-virus engine ClamAV.

ClamAV has a limited set of scanning capabilities and limited performance compared to third-party products. Hence, expect ClamAV to only provide basic protection.

On the other hand, ClamAV is shipped with SUSE Linux Enterprise Server and it can be included during server installation. This makes it easy to fulfill this requirement, but the drawbacks compared to third-party products need to be clearly understood.

A.3.6 Requirement 6: Develop and maintain secure systems and applications

The major part of this requirement concerns in-house software development, documentation, and design questions that are beyond the scope of this document. However, SUSE Linux Enterprise Server provides tools that help keep your systems safe:

  • The software package manager Zypper is a powerful instrument of SUSE Linux Enterprise Server. Among other things, it resolves dependencies of packages, products, patterns, and patches, has a locking mechanism to prevent package installation, and provides a complete update stack to keep the system up-to-date and protected against know security issues.

    zypper is part of any SUSE Linux Enterprise Server installation and has direct access to the update repositories after system registration.

    For information about Zypper, see Section 6.1, “Using Zypper”.

  • For system management, SUSE provides SUSE Manager that provides an efficient way to keep systems up-to-date. It offers seamless management of both SUSE Linux Enterprise Server and RedHat Enterprise Linux client systems. This is particularly useful in larger system environments, when you need to check the current update status of each system and to react to known security risks.

    For information about SUSE Manager, see https://www.suse.com/documentation/suse-manager/.

6.2.a Examine policies and procedures related to security patch installation to verify processes are defined for: (1) Installation of applicable critical vendor-supplied security patches within one month of release, (2) Installation of all applicable vendor-supplied security patches within an appropriate time frame (for example, within three months).

To identify patches that need to be installed to secure your system, do the following:

First, refresh all software repositories, so you have up-to-date information:

tux > sudo zypper refresh

Then use the patch-related commands of Zypper:

  • Search for important security fixes that have not yet been installed:

    tux > zypper list-patches --category security --severity important
  • It is also possible to search for CVE or SUSE Bugzilla numbers. By default, only necessary patches are listed by this command. To also show patches that have already been installed, use the parameter --all:

    tux > zypper list-patches --all --cve=CVE-2016-4957
  • To list details of individual patches, use the patch-info subcommand:

    tux > zypper patch-info SUSE-SLE-SERVER-12-SP1-2016-600
  • To install only important security patches, use the patch subcommand.

    tux > sudo zypper patch --category security --severity important

To perform updates automatically, the parameter --non-interactive, that is supported by all Zypper subcommands, is helpful.

For more information about Zypper, see Section 6.1, “Using Zypper”.

A.3.7 Requirement 7: Restrict access to cardholder data by business need to know

OS access control is a complex topic. Again, this PCI-DSS requirement is not specified precisely and does not specifically state to which degree the restrictions need to be implemented. SUSE Linux Enterprise Server comes with all general Linux tools to limit and restrict access to certain system areas and components:

  • Access can be controlled via specific users and groups of users using the traditional Unix permission settings.

    For information about managing permissions, see Chapter 10, Access Control Lists in Linux.

  • A more flexible mechanism for file systems are Access Control Lists (ACLs) that offer a more granular approach. SELinux can be used for maximum system separation and to protect processes from gaining more resources and access then allowed. SELinux or AppArmor are beyond the scope of this document but should be employed to protect critical systems that are likely to be targeted.

7.1.2 Restrict access to privileged user IDs to least privileges necessary to perform job responsibilities.

The standard Unix permissions allow setting Read, Write, and Execution flags to user and group IDs. A general group called others or world defines the access for users that do not fit into the first two groups. This provides a straightforward way to grant or deny access to file system resources.

ACLs provide an extra level of restrictions. It is possible to set read-write access for one user ID and only read access to a second one. The same goes for group IDs.

The commands getfacl and setfacl (on SUSE Linux Enterprise Server shipped with the package acl) allow direct modification of file system resources. For example, to check and set ACL restrictions of the file /tmp/test.txt for the user wilber:

tux > getfacl /tmp/test.txt
# file: /tmp/test.txt
# owner: tux
# group: users
user::r--
group::r--
other::r--

tux > setfacl -m "u:wilber:rw" /tmp/test.txt

tux > getfacl /tmp/test.txt
# file: /tmp/test.txt
# owner: tux
# group: users
user::rw-
user:wilber:r--
group::r--
mask::r--
other::r--

Standard Unix permissions include the so-called Sticky Bit. This allows the execution of certain programs with higher privileges then the user who is executing those programs. The best example of this is the passwd tool that needs to modify the /etc/shadow to change the user password.

For a more gradual approach to explicitly allowing certain operations or behaviors to binaries, use extended capabilities. As an example for a command that uses extended capabilities by default, consider ping (from the package iputils).

ping sends ICMP IP packets over the network card. For this, it needs the CAP_NET_RAW capability to be Effective and Permitted (+ep):

root # sudo getcap /usr/bin/ping
/usr/bin/ping = cap_net_raw+ep

Login access control to the system can be managed using Pluggable Authentication Modules (PAM). There are several modules available in SUSE Linux Enterprise Server that allow setups such as logging the login time, multiple authentication mechanisms and central databases like NIS, LDAP or Active Directory.

For more information about managing permissions, see Chapter 10, Access Control Lists in Linux.

A.3.8 Requirement 8: Identify and authenticate access to system component

Ideally, use a central database with user information and a unique identifier (UID) to grant or deny access to certain system components. This makes it easy to give administrators special access to group of servers or a database engineer permission to a certain DBMS system.

On a stand-alone server, unique identifiers are managed via the standard Linux user and group IDs. These are listed inside /etc/passwd and /etc/group.

8.1.4 Remove/disable inactive user accounts within 90 days.

In this context, there are many advantages to using a centralized infrastructure for user accounts like NIS, LDAP, or Active Directory:

  • It is easy to identify and automatically disable inactive accounts.

  • User accounts only need to be disabled in one place. After their access is revoked, the user cannot use any service that relies on the centralized account infrastructure.

However, if you are using local accounts, these can be checked for inactivity when a user is logging in. This module checks the last login time recorded in /var/log/lastlog and calculates the number of days since. By default, access is denied when the inactivity reaches 90 days.

To list the local accounts last login time use the command lastlog.

8.1.6 Limit repeated access attempts by locking out the user ID after not more than six attempts.

As stated in 8.1.4 Remove/disable inactive user accounts within 90 days. , a centralized account infrastructure will have this capability. On SUSE Linux Enterprise Server systems, access attempts can be checked and limited with the pam_tally2 PAM module. The module is executed during login time and checks the recorded failed attempts since the last successful login. To check and reset the account status, use the tool pam_tally2.

8.1.7 Set the lockout duration to a minimum of 30 minutes or until an administrator enables the user ID.

The PAM module pam_tally2 described in 8.1.6 Limit repeated access attempts by locking out the user ID after not more than six attempts. can be used to lock an account for a given time after a failed login attempt. The parameter unlock_time=1800 must be specified in the PAM configuration. By default, only the administrator can reactivate a locked account.

8.3.1 Incorporate multi-factor authentication for all non-console access into the CDE for personnel with administrative access.

To authenticate users for administrative access with multiple factors, use the following methods:

  • Use Pluggable Authentication Modules (PAM): This increases flexibility when adding new methods to the authentication process and when adjusting it.

    For third-party one-time password (OTP) products, there is usually also a Linux PAM module available.

    For information about PAM, see Chapter 2, Authentication with PAM.

  • To add multi-factor authentication for SSH connections, mandate use of public keys in addition to passwords.

    To connect to a system, it is then necessary to prove possession of an appropriate private key. At the second stage, you then enter a password. This means attackers need to acquire a private key before they can even try to brute force a password prompt.

8.3.2 Incorporate multi-factor authentication for all remote network access (both user and administrator, and including third-party access for support or maintenance) originating from outside the entity’s network.

For details, see 8.3.1 Incorporate multi-factor authentication for all non-console access into the CDE for personnel with administrative access. .

A.3.9 Requirement 9: Restrict physical access to cardholder data

Physical access to systems that are involved in processing cardholder data are not within the scope of general operating system security. Appropriate facility entry controls must be in place to allow onside personnel employees and visitors to access systems directly.

A.3.10 Requirement 10: Track and monitor all access to network resources and cardholder data

To track user activities, it is important to have a synchronized time reference. This is done via the NTP protocol that allows servers to keep their local time in synchronization with a central system. The central NTP server inside the cardholder data environment (CDE) should not rely on external connections to the Internet to update the system time. Alternatively, system time can be updated using DCF77 radio transmissions or a GPS receiver.

A synchronized time reference makes it easier to correlate events inside recorded log files. This reference can include general system log entries collected by a central system log server or kernel audit messages by the daemon audit.

For information about auditing, see Part VI, “The Linux Audit Framework.

All subsections of this requirement relevant to auditing can be complied with by defining auditing rules that in a central storage.

A.3.11 Requirement 11: Regularly Test Security Systems and Processes

Testing the discussed security mechanisms is also a key requirement for PCI-DSS. Evaluating the configurations and testing logging mechanisms can protect against know security risks and ensure that essential information are available to identify possible security breaches. Testing capabilities should be considered during system design already.

To keep track of system integrity, SUSE Linux Enterprise Server comes with the Advanced Intrusion Detection Environment (AIDE). AIDE creates a hash value database of all relevant OS files. After initialization, it can be used to verify the integrity of all previously saved files. To employ AIDE, it is best to regularly create database snapshots and save them to a central system on which you can evaluate possible modifications.

For more information about AIDE, see Chapter 13, Intrusion Detection with AIDE.

A.3.12 Requirement 12: Maintain a Policy That Addresses Information Security for All Personnel

Any organization that handles valuable information should have general security policy. All relevant aspects should be included to make it clear for employees and stakeholders about possible risks and how to avoid them.

All security policies should also be evaluated regularly and adjusted to keep the protection level as high as possible.

B Documentation Updates

  • Filename: security_docupdates.xml
  • ID: app.security.docupdates

This chapter lists content changes for this document.

This manual was updated on the following dates:

B.1 January 2018 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)

Chapter 2, Authentication with PAM

B.3 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)

General
Part I, “Authentication”
Chapter 14, SSH: Secure Network Operations
Chapter 15, Masquerading and Firewalls

B.4 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)

General
  • The e-mail address for documentation feedback has changed to doc-team@suse.com.

  • The documentation for Docker has been enhanced and renamed to Docker Guide.

B.5 March 2016 (Maintenance Release of SUSE Linux Enterprise Server 12 SP1)

B.6 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)

General
  • SMT Guide is now part of the documentation for SUSE Linux Enterprise Server.

  • Add-ons provided by SUSE have been renamed as modules and extensions. The manuals have been updated to reflect this change.

  • Numerous small fixes and additions to the documentation, based on technical feedback.

  • The registration service has been changed from Novell Customer Center to SUSE Customer Center.

  • In YaST, you will now reach Network Settings via the System group. Network Devices is gone (https://bugzilla.suse.com/show_bug.cgi?id=867809).

Chapter 4, Setting Up Authentication Servers and Clients Using YaST

Updated the chapter to reflect new GUI improvements for Kerberos/LDAP client (Fate #316349).

Chapter 8, Configuring Security Settings with YaST

Updated chapter because of systemd-related changes (Fate #318425).

Chapter 15, Masquerading and Firewalls
Chapter 30, Configuring SELinux
Bugfixes

B.8 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)

General
  • Removed all KDE documentation and references because KDE is no longer shipped.

  • Removed all references to SuSEconfig, which is no longer supported (Fate #100011).

  • Move from System V init to systemd (Fate #310421). Updated affected parts of the documentation.

  • YaST Runlevel Editor has changed to Services Manager (Fate #312568). Updated affected parts of the documentation.

  • Removed all references to ISDN support, as ISDN support has been removed (Fate #314594).

  • Removed all references to the YaST DSL module as it is no longer shipped (Fate #316264).

  • Removed all references to the YaST Modem module as it is no longer shipped (Fate #316264).

  • Btrfs has become the default file system for the root partition (Fate #315901). Updated affected parts of the documentation.

  • The dmesg now provides human-readable time stamps in ctime()-like format (Fate #316056). Updated affected parts of the documentation.

  • syslog and syslog-ng have been replaced by rsyslog (Fate #316175). Updated affected parts of the documentation.

  • MariaDB is now shipped as the relational database instead of MySQL (Fate #313595). Updated affected parts of the documentation.

  • SUSE-related products are no longer available from http://download.novell.com but from http://download.suse.com. Adjusted links accordingly.

  • Novell Customer Center has been replaced with SUSE Customer Center. Updated affected parts of the documentation.

  • /var/run is mounted as tmpfs (Fate #303793). Updated affected parts of the documentation.

  • The following architectures are no longer supported: IA64 and x86. Updated affected parts of the documentation.

  • The traditional method for setting up the network with ifconfig has been replaced by wicked. Updated affected parts of the documentation.

  • A lot of networking commands are deprecated and have been replaced by newer commands (usually ip). Updated affected parts of the documentation.

    arp: ip neighbor
    ifconfig: ip addr, ip link
    iptunnel: ip tunnel
    iwconfig: iw
    nameif: ip link, ifrename
    netstat: ss, ip route, ip -s link, ip maddr
    route: ip route
  • Numerous small fixes and additions to the documentation, based on technical feedback.

Chapter 2, Authentication with PAM

The pam_pwcheck module has been replaced with pam_cracklib and pam_pwhistory. Updated chapter to reflect this change.

Chapter 4, Setting Up Authentication Servers and Clients Using YaST

Added a chapter about the new YaST authentication module for Kerberos and LDAP (Fate #316349). The chapter consists of two parts: Section 4.2, “Configuring an Authentication Client with YaST” and Section 4.2, “Configuring an Authentication Client with YaST” (Fate #308902).

Chapter 5, LDAP—A Directory Service

Updated chapter to reflect the changes in YaST regarding authentication setup (Fate #316349).

Chapter 6, Network Authentication with Kerberos

Updated chapter to reflect the changes in YaST regarding authentication setup (Fate #316349).

Chapter 9, Authorization with PolKit

Updated chapter to reflect major software updates.

Chapter 14, SSH: Secure Network Operations
Chapter 17, Managing X.509 Certification

The YaST CA module now allows to export key and certificate into different files. See Section 17.2.5, “Changing Default Values” (Fate #305490).

Part IV, “Confining Privileges with AppArmor
Part VI, “The Linux Audit Framework

Numerous small fixes and additions, based on technical feedback.

Obsolete Content
Bugfixes
SUSE Linux Enterprise Server 12 SP3

System Analysis and Tuning Guide

An administrator's guide for problem detection, resolution and optimization. Find how to inspect and optimize your system by means of monitoring tools and how to efficiently manage resources. Also contains an overview of common problems and solutions and of additional help and documentation resources.

Publication Date: April 04, 2018
About This Guide
Available Documentation
Feedback
Documentation Conventions
I Basics
1 General Notes on System Tuning
1.1 Be Sure What Problem to Solve
1.2 Rule Out Common Problems
1.3 Finding the Bottleneck
1.4 Step-by-step Tuning
II System Monitoring
2 System Monitoring Utilities
2.1 Multi-Purpose Tools
2.2 System Information
2.3 Processes
2.4 Memory
2.5 Networking
2.6 The /proc File System
2.7 Hardware Information
2.8 Files and File Systems
2.9 User Information
2.10 Time and Date
2.11 Graph Your Data: RRDtool
3 Analyzing and Managing System Log Files
3.1 System Log Files in /var/log/
3.2 Viewing and Parsing Log Files
3.3 Managing Log Files with logrotate
3.4 Monitoring Log Files with logwatch
3.5 Using logger to Make System Log Entries
III Kernel Monitoring
4 SystemTap—Filtering and Analyzing System Data
4.1 Conceptual Overview
4.2 Installation and Setup
4.3 Script Syntax
4.4 Example Script
4.5 User Space Probing
4.6 For More Information
5 Kernel Probes
5.1 Supported Architectures
5.2 Types of Kernel Probes
5.3 Kprobes API
5.4 debugfs Interface
5.5 For More Information
6 Hardware-Based Performance Monitoring with Perf
6.1 Hardware-Based Monitoring
6.2 Sampling and Counting
6.3 Installing Perf
6.4 Perf Subcommands
6.5 Counting Particular Types of Event
6.6 Recording Events Specific to Particular Commands
6.7 For More Information
7 OProfile—System-Wide Profiler
7.1 Conceptual Overview
7.2 Installation and Requirements
7.3 Available OProfile Utilities
7.4 Using OProfile
7.5 Using OProfile's GUI
7.6 Generating Reports
7.7 For More Information
IV Resource Management
8 General System Resource Management
8.1 Planning the Installation
8.2 Disabling Unnecessary Services
8.3 File Systems and Disk Access
9 Kernel Control Groups
9.1 Technical Overview and Definitions
9.2 Scenario
9.3 Control Group Subsystems
9.4 Using Controller Groups
9.5 For More Information
10 Automatic Non-Uniform Memory Access (NUMA) Balancing
10.1 Implementation
10.2 Configuration
10.3 Monitoring
10.4 Impact
11 Power Management
11.1 Power Management at CPU Level
11.2 In-Kernel Governors
11.3 The cpupower Tools
11.4 Special Tuning Options
11.5 Troubleshooting
11.6 For More Information
V Kernel Tuning
12 Tuning I/O Performance
12.1 Switching I/O Scheduling
12.2 Available I/O Elevators
12.3 I/O Barrier Tuning
12.4 Enable blk-mq I/O Path for SCSI by Default
13 Tuning the Task Scheduler
13.1 Introduction
13.2 Process Classification
13.3 Completely Fair Scheduler
13.4 For More Information
14 Tuning the Memory Management Subsystem
14.1 Memory Usage
14.2 Reducing Memory Usage
14.3 Virtual Memory Manager (VM) Tunable Parameters
14.4 Monitoring VM Behavior
15 Tuning the Network
15.1 Configurable Kernel Socket Buffers
15.2 Detecting Network Bottlenecks and Analyzing Network Traffic
15.3 Netfilter
15.4 Improving the Network Performance with Receive Packet Steering (RPS)
15.5 For More Information
VI Handling System Dumps
16 Tracing Tools
16.1 Tracing System Calls with strace
16.2 Tracing Library Calls with ltrace
16.3 Debugging and Profiling with Valgrind
16.4 For More Information
17 Kexec and Kdump
17.1 Introduction
17.2 Required Packages
17.3 Kexec Internals
17.4 Calculating crashkernel Allocation Size
17.5 Basic Kexec Usage
17.6 How to Configure Kexec for Routine Reboots
17.7 Basic Kdump Configuration
17.8 Analyzing the Crash Dump
17.9 Advanced Kdump Configuration
17.10 For More Information
VII Synchronized Clocks with Precision Time Protocol
18 Precision Time Protocol
18.1 Introduction to PTP
18.2 Using PTP
18.3 Synchronizing the Clocks with phc2sys
18.4 Examples of Configurations
18.5 PTP and NTP
A Documentation Updates
A.1 December 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)
A.2 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)
A.3 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)
A.4 March 2016 (Maintenance Release of SUSE Linux Enterprise Server 12 SP1)
A.5 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)
A.6 February 2015 (Documentation Maintenance Update)
A.7 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)
B GNU Licenses
B.1 GNU Free Documentation License

Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

About This Guide

  • Filename: tuning_intro.xml
  • ID: preface.tuning

SUSE Linux Enterprise Server is used for a broad range of usage scenarios in enterprise and scientific data centers. SUSE has ensured SUSE Linux Enterprise Server is set up in a way that it accommodates different operation purposes with optimal performance. However, SUSE Linux Enterprise Server must meet very different demands when employed on a number crunching server compared to a file server, for example.

It is not possible to ship a distribution that is optimized for all workloads. Different workloads vary substantially in some aspects. Most important among those are I/O access patterns, memory access patterns, and process scheduling. A behavior that perfectly suits a certain workload might reduce performance of another workload. For example, I/O-intensive tasks, such as handling database requests, usually have completely different requirements than CPU-intensive tasks, such as video encoding. The versatility of Linux makes it possible to configure your system in a way that it brings out the best in each usage scenario.

This manual introduces you to means to monitor and analyze your system. It describes methods to manage system resources and to tune your system. This guide does not offer recipes for special scenarios, because each server has got its own different demands. It rather enables you to thoroughly analyze your servers and make the most out of them.

Part I, “Basics”

Tuning a system requires a carefully planned proceeding. Learn which steps are necessary to successfully improve your system.

Part II, “System Monitoring”

Linux offers a large variety of tools to monitor almost every aspect of the system. Learn how to use these utilities and how to read and analyze the system log files.

Part III, “Kernel Monitoring”

The Linux kernel itself offers means to examine every nut, bolt and screw of the system. This part introduces you to SystemTap, a scripting language for writing kernel modules that can be used to analyze and filter data. Collect debugging information and find bottlenecks by using kernel probes and Perf. Last, monitor applications with Oprofile.

Part IV, “Resource Management”

Learn how to set up a tailor-made system fitting exactly the server's need. Get to know how to use power management while at the same time keeping the performance of a system at a level that matches the current requirements.

Part V, “Kernel Tuning”

The Linux kernel can be optimized either by using sysctl, via the /proc and /sys file systems or by kernel command line parameters. This part covers tuning the I/O performance and optimizing the way how Linux schedules processes. It also describes basic principles of memory management and shows how memory management can be fine-tuned to suit needs of specific applications and usage patterns. Furthermore, it describes how to optimize network performance.

Part VI, “Handling System Dumps”

This part enables you to analyze and handle application or system crashes. It introduces tracing tools such as strace or ltrace and describes how to handle system crashes using Kexec and Kdump.

Tip
Tip: Getting the SUSE Linux Enterprise SDK

The SDK is a module for SUSE Linux Enterprise and is available via an online channel from the SUSE Customer Center. Alternatively, go to http://download.suse.com/, search for SUSE Linux Enterprise Software Development Kit and download it from there. Refer to Chapter 14, Installing Modules, Extensions, and Third Party Add-On Products for details.

1 Available Documentation

  • Filename: common_intro_available_doc_i.xml
  • ID: no ID found
Note
Note: Online Documentation and Latest Updates

Documentation for our products is available at http://www.suse.com/documentation/, where you can also find the latest updates, and browse or download the documentation in various formats.

In addition, the product documentation is usually available in your installed system under /usr/share/doc/manual.

The following documentation is available for this product:

Installation Quick Start

Lists the system requirements and guides you step-by-step through the installation of SUSE Linux Enterprise Server from DVD, or from an ISO image.

Deployment Guide

Shows how to install single or multiple systems and how to exploit the product inherent capabilities for a deployment infrastructure. Choose from various approaches, ranging from a local installation or a network installation server to a mass deployment using a remote-controlled, highly-customized, and automated installation technique.

Administration Guide

Covers system administration tasks like maintaining, monitoring and customizing an initially installed system.

Virtualization Guide

Describes virtualization technology in general, and introduces libvirt—the unified interface to virtualization—and detailed information on specific hypervisors.

Storage Administration Guide

Provides information about how to manage storage devices on a SUSE Linux Enterprise Server.

AutoYaST

AutoYaST is a system for unattended mass deployment SUSE Linux Enterprise Server systems using an AutoYaST profile containing installation and configuration data. The manual guides you through the basic steps of auto-installation: preparation, installation, and configuration.

Security Guide

Introduces basic concepts of system security, covering both local and network security aspects. Shows how to use the product inherent security software like AppArmor or the auditing system that reliably collects information about any security-relevant events.

Security and Hardening Guide

Deals with the particulars of installing and setting up a secure SUSE Linux Enterprise Server, and additional post-installation processes required to further secure and harden that installation. Supports the administrator with security-related choices and decisions.

System Analysis and Tuning Guide

An administrator's guide for problem detection, resolution and optimization. Find how to inspect and optimize your system by means of monitoring tools and how to efficiently manage resources. Also contains an overview of common problems and solutions and of additional help and documentation resources.

SMT Guide

An administrator's guide to Subscription Management Tool—a proxy system for SUSE Customer Center with repository and registration targets. Learn how to install and configure a local SMT server, mirror and manage repositories, manage client machines, and configure clients to use SMT.

GNOME User Guide

Introduces the GNOME desktop of SUSE Linux Enterprise Server. It guides you through using and configuring the desktop and helps you perform key tasks. It is intended mainly for end users who want to make efficient use of GNOME as their default desktop.

2 Feedback

  • Filename: common_intro_feedback_i.xml
  • ID: no ID found

Several feedback channels are available:

Bugs and Enhancement Requests

For services and support options available for your product, refer to http://www.suse.com/support/.

Help for openSUSE is provided by the community. Refer to https://en.opensuse.org/Portal:Support for more information.

To report bugs for a product component, go to https://scc.suse.com/support/requests, log in, and click Create New.

User Comments

We want to hear your comments about and suggestions for this manual and the other documentation included with this product. Use the User Comments feature at the bottom of each page in the online documentation or go to http://www.suse.com/documentation/feedback.html and enter your comments there.

Mail

For feedback on the documentation of this product, you can also send a mail to doc-team@suse.com. Make sure to include the document title, the product version and the publication date of the documentation. To report errors or suggest enhancements, provide a concise description of the problem and refer to the respective section number and page (or URL).

3 Documentation Conventions

  • Filename: common_intro_typografie_i.xml
  • ID: no ID found

The following notices and typographical conventions are used in this documentation:

  • /etc/passwd: directory names and file names

  • PLACEHOLDER: replace PLACEHOLDER with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • package name : name of a package

  • Alt, AltF1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File › Save As: menu items, buttons

  • x86_64 This paragraph is only relevant for the AMD64/Intel 64 architecture. The arrows mark the beginning and the end of the text block.

    System z, POWER This paragraph is only relevant for the architectures z Systems and POWER. The arrows mark the beginning and the end of the text block.

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

  • Commands that must be run with root privileges. Often you can also prefix these commands with the sudo command to run them as non-privileged user.

    root # command
    tux > sudo command
  • Commands that can be run by non-privileged users.

    tux > command
  • Notices

    Warning
    Warning: Warning Notice

    Vital information you must be aware of before proceeding. Warns you about security issues, potential loss of data, damage to hardware, or physical hazards.

    Important
    Important: Important Notice

    Important information you should be aware of before proceeding.

    Note
    Note: Note Notice

    Additional information, for example about differences in software versions.

    Tip
    Tip: Tip Notice

    Helpful information, like a guideline or a piece of practical advice.

Part I Basics

1 General Notes on System Tuning

This manual discusses how to find the reasons for performance problems and provides means to solve these problems. Before you start tuning your system, you should make sure you have ruled out common problems and have found the cause for the problem. You should also have a detailed plan on how to tune the system, because applying random tuning tips often will not help and could make things worse.

1 General Notes on System Tuning

  • Filename: tuning_how.xml
  • ID: cha.tuning.basics
Abstract

This manual discusses how to find the reasons for performance problems and provides means to solve these problems. Before you start tuning your system, you should make sure you have ruled out common problems and have found the cause for the problem. You should also have a detailed plan on how to tune the system, because applying random tuning tips often will not help and could make things worse.

Procedure 1.1: General Approach When Tuning a System
  1. Specify the problem that needs to be solved.

  2. In case the degradation is new, identify any recent changes to the system.

  3. Identify why the issue is considered a performance problem.

  4. Specify a metric that can be used to analyze performance. This metric could for example be latency, throughput, the maximum number of users that are simultaneously logged in, or the maximum number of active users.

  5. Measure current performance using the metric from the previous step.

  6. Identify the subsystem(s) where the application is spending the most time.

    1. Monitor the system and/or the application.

    2. Analyze the data, categorize where time is being spent.

  7. Tune the subsystem identified in the previous step.

  8. Remeasure the current performance without monitoring using the same metric as before.

  9. If performance is still not acceptable, start over with Step 3.

1.1 Be Sure What Problem to Solve

Before starting to tuning a system, try to describe the problem as exactly as possible. A statement like The system is slow! is not a helpful problem description. For example, it could make a difference whether the system speed needs to be improved in general or only at peak times.

Furthermore, make sure you can apply a measurement to your problem, otherwise you cannot verify if the tuning was a success or not. You should always be able to compare before and after. Which metrics to use depends on the scenario or application you are looking into. Relevant Web server metrics, for example, could be expressed in terms of:

Latency

The time to deliver a page

Throughput

Number of pages served per second or megabytes transferred per second

Active Users

The maximum number of users that can be downloading pages while still receiving pages within an acceptable latency

1.2 Rule Out Common Problems

A performance problem often is caused by network or hardware problems, bugs, or configuration issues. Make sure to rule out problems such as the ones listed below before attempting to tune your system:

  • Check the output of the systemd journal (see Chapter 15, journalctl: Query the systemd Journal) for unusual entries.

  • Check (using top or ps) whether a certain process misbehaves by eating up unusual amounts of CPU time or memory.

  • Check for network problems by inspecting /proc/net/dev.

  • In case of I/O problems with physical disks, make sure it is not caused by hardware problems (check the disk with the smartmontools) or by a full disk.

  • Ensure that background jobs are scheduled to be carried out in times the server load is low. Those jobs should also run with low priority (set via nice).

  • If the machine runs several services using the same resources, consider moving services to another server.

  • Last, make sure your software is up-to-date.

1.3 Finding the Bottleneck

Finding the bottleneck very often is the hardest part when tuning a system. SUSE Linux Enterprise Server offers many tools to help you with this task. See Part II, “System Monitoring” for detailed information on general system monitoring applications and log file analysis. If the problem requires a long-time in-depth analysis, the Linux kernel offers means to perform such analysis. See Part III, “Kernel Monitoring” for coverage.

Once you have collected the data, it needs to be analyzed. First, inspect if the server's hardware (memory, CPU, bus) and its I/O capacities (disk, network) are sufficient. If these basic conditions are met, the system might benefit from tuning.

1.4 Step-by-step Tuning

Make sure to carefully plan the tuning itself. It is of vital importance to only do one step at a time. Only by doing so you can measure if the change provided an improvement or even had a negative impact. Each tuning activity should be measured over a sufficient time period to ensure you can do an analysis based on significant data. If you cannot measure a positive effect, do not make the change permanent. Chances are, that it might have a negative effect in the future.

Part II System Monitoring

2 System Monitoring Utilities

There are number of programs, tools, and utilities which you can use to examine the status of your system. This chapter introduces some and describes their most important and frequently used parameters.

3 Analyzing and Managing System Log Files

System log file analysis is one of the most important tasks when analyzing the system. In fact, looking at the system log files should be the first thing to do when maintaining or troubleshooting a system. SUSE Linux Enterprise Server automatically logs almost everything that happens on the system i…

2 System Monitoring Utilities

  • Filename: utilities.xml
  • ID: cha.util
Abstract

There are number of programs, tools, and utilities which you can use to examine the status of your system. This chapter introduces some and describes their most important and frequently used parameters.

Note
Note: Gathering and Analyzing System Information with supportconfig

Apart from the utilities presented in the following, SUSE Linux Enterprise Server also contains supportconfig, a tool to create reports about the system such as: current kernel version, hardware, installed packages, partition setup and much more. These reports are used to provide the SUSE support with needed information in case a support ticket is created. However, they can also be analyzed for known issues to help resolve problems faster. For this purpose, SUSE Linux Enterprise Server provides both an appliance and a command line tool for Supportconfig Analysis (SCA). See Chapter 39, Gathering System Information for Support for details.

For each of the described commands, examples of the relevant outputs are presented. In the examples, the first line is the command itself (after the tux > or root #). Omissions are indicated with square brackets ([...]) and long lines are wrapped where necessary. Line breaks for long lines are indicated by a backslash (\).

tux > command -x -y
output line 1
output line 2
output line 3 is annoyingly long, so long that \
    we need to break it
output line 4
[...]
output line 98
output line 99

The descriptions have been kept short so that we can include as many utilities as possible. Further information for all the commands can be found in the manual pages. Most of the commands also understand the parameter --help, which produces a brief list of possible parameters.

2.1 Multi-Purpose Tools

While most Linux system monitoring tools monitor only a single aspect of the system, there are a few tools with a broader scope. To get an overview and find out which part of the system to examine further, use these tools first.

2.1.1 vmstat

vmstat collects information about processes, memory, I/O, interrupts and CPU. If called without a sampling rate, it displays average values since the last reboot. When called with a sampling rate, it displays actual samples:

Example 2.1: vmstat Output on a Lightly Used Machine
tux > vmstat 2
procs -----------memory---------- ---swap-- -----io---- -system-- ------cpu-----
 r  b   swpd   free   buff  cache   si   so    bi    bo   in   cs us sy id wa st
 1  0  44264  81520    424 935736    0    0    12    25   27   34  1  0 98   0  0
 0  0  44264  81552    424 935736    0    0     0     0   38   25  0  0 100  0  0
 0  0  44264  81520    424 935732    0    0     0     0   23   15  0  0 100  0  0
 0  0  44264  81520    424 935732    0    0     0     0   36   24  0  0 100  0  0
 0  0  44264  81552    424 935732    0    0     0     0   51   38  0  0 100  0  0
Example 2.2: vmstat Output on a Heavily Used Machine (CPU bound)
tux > vmstat 2
procs -----------memory----------- ---swap-- -----io---- -system-- -----cpu------
 r  b   swpd   free   buff   cache   si   so    bi    bo   in   cs us sy id wa st
32  1  26236 459640 110240 6312648    0    0  9944     2 4552 6597 95  5  0  0  0
23  1  26236 396728 110336 6136224    0    0  9588     0 4468 6273 94  6  0  0  0
35  0  26236 554920 110508 6166508    0    0  7684 27992 4474 4700 95  5  0  0  0
28  0  26236 518184 110516 6039996    0    0 10830     4 4446 4670 94  6  0  0  0
21  5  26236 716468 110684 6074872    0    0  8734 20534 4512 4061 96  4  0  0  0
Tip
Tip: First Line of Output

The first line of the vmstat output always displays average values since the last reboot.

The columns show the following:

r

Shows the number of processes in a runnable state. These processes are either executing or waiting for a free CPU slot. If the number of processes in this column is constantly higher than the number of CPUs available, this may be an indication of insufficient CPU power.

b

Shows the number of processes waiting for a resource other than a CPU. A high number in this column may indicate an I/O problem (network or disk).

swpd

The amount of swap space (KB) currently used.

free

The amount of unused memory (KB).

inact

Recently unused memory that can be reclaimed. This column is only visible when calling vmstat with the parameter -a (recommended).

active

Recently used memory that normally does not get reclaimed. This column is only visible when calling vmstat with the parameter -a (recommended).

buff

File buffer cache (KB) in RAM that contains file system metadata. This column is not visible when calling vmstat with the parameter -a.

cache

Page cache (KB) in RAM with the actual contents of files. This column is not visible when calling vmstat with the parameter -a.

si / so

Amount of data (KB) that is moved from swap to RAM (si) or from RAM to swap (so) per second. High so values over a long period of time may indicate that an application is leaking memory and the leaked memory is being swapped out. High si values over a long period of time could mean that an application that was inactive for a very long time is now active again. Combined high si and so values for prolonged periods of time are evidence of swap thrashing and may indicate that more RAM needs to be installed in the system because there is not enough memory to hold the working set size.

bi

Number of blocks per second received from a block device (for example, a disk read). Note that swapping also impacts the values shown here. The block size may vary between file systems but can be determined using the stat utility. If throughput data is required then iostat may be used.

bo

Number of blocks per second sent to a block device (for example, a disk write). Note that swapping also impacts the values shown here.

in

Interrupts per second. A high value may indicate a high I/O level (network and/or disk), but could also be triggered for other reasons such as inter-processor interrupts triggered by another activity. Make sure to also check /proc/interrupts to identify the source of interrupts.

cs

Number of context switches per second. This is the number of times that the kernel replaces executable code of one program in memory with that of another program.

us

Percentage of CPU usage executing application code.

sy

Percentage of CPU usage executing kernel code.

id

Percentage of CPU time spent idling. If this value is zero over a longer time, your CPU(s) are working to full capacity. This is not necessarily a bad sign—rather refer to the values in columns r and b to determine if your machine is equipped with sufficient CPU power.

wa

If "wa" time is non-zero, it indicates throughput lost because of waiting for I/O. This may be inevitable, for example, if a file is being read for the first time, background writeback cannot keep up, and so on. It can also be an indicator for a hardware bottleneck (network or hard disk). Lastly, it can indicate a potential for tuning the virtual memory manager (refer to Chapter 14, Tuning the Memory Management Subsystem).

st

Percentage of CPU time stolen from a virtual machine.

See vmstat --help for more options.

2.1.2 dstat

  • Filename: tuning_utilities_dstat.xml
  • ID: sec.util.multi.dstat

dstat is a replacement for tools such as vmstat, iostat, netstat, or ifstat. dstat displays information about the system resources in real time. For example, you can compare disk usage in combination with interrupts from the IDE controller, or compare network bandwidth with the disk throughput (in the same interval).

By default, its output is presented in readable tables. Alternatively, CSV output can be produced which is suitable as a spreadsheet import format.

It is written in Python and can be enhanced with plug-ins.

This is the general syntax:

dstat [-afv] [OPTIONS..] [DELAY [COUNT]]

All options and parameters are optional. Without any parameter, dstat displays statistics about CPU (-c, --cpu), disk (-d, --disk), network (-n, --net), paging (-g, --page), and the interrupts and context switches of the system (-y, --sys); it refreshes the output every second ad infinitum:

root # dstat
You did not select any stats, using -cdngy by default.
----total-cpu-usage---- -dsk/total- -net/total- ---paging-- ---system--
usr sys idl wai hiq siq| read  writ| recv  send|  in   out | int   csw
  0   0 100   0   0   0|  15k   44k|   0     0 |   0    82B| 148   194
  0   0 100   0   0   0|   0     0 |5430B  170B|   0     0 | 163   187
  0   0 100   0   0   0|   0     0 |6363B  842B|   0     0 | 196   185
-a, --all

equal to -cdngy (default)

-f, --full

expand -C, -D, -I, -N and -S discovery lists

-v, --vmstat

equal to -pmgdsc, -D total

DELAY

delay in seconds between each update

COUNT

the number of updates to display before exiting

The default delay is 1 and the count is unspecified (unlimited).

For more information, see the man page of dstat and its Web page at http://dag.wieers.com/home-made/dstat/.

2.1.3 System Activity Information: sar

sar can generate extensive reports on almost all important system activities, among them CPU, memory, IRQ usage, IO, or networking. It can also generate reports on the fly. sar gathers all their data from the /proc file system.

Note
Note: sysstat Package

sar is a part of the sysstat package either with YaST, or with zypper in sysstat.

2.1.3.1 Generating reports with sar

To generate reports on the fly, call sar with an interval (seconds) and a count. To generate reports from files specify a file name with the option -f instead of interval and count. If file name, interval and count are not specified, sar attempts to generate a report from /var/log/sa/saDD, where DD stands for the current day. This is the default location to where sadc (the system activity data collector) writes its data. Query multiple files with multiple -f options.

sar 2 10                         # on-the-fly report, 10 times every 2 seconds
sar -f ~/reports/sar_2014_07_17  # queries file sar_2014_07_17
sar                              # queries file from today in /var/log/sa/
cd /var/log/sa && \
sar -f sa01 -f sa02              # queries files /var/log/sa/0[12]

Find examples for useful sar calls and their interpretation below. For detailed information on the meaning of each column, refer to the man (1) of sar. Also refer to the man page for more options and reports—sar offers plenty of them.

2.1.3.1.1 CPU Usage Report: sar

When called with no options, sar shows a basic report about CPU usage. On multi-processor machines, results for all CPUs are summarized. Use the option -P ALL to also see statistics for individual CPUs.

root # sar 10 5
Linux 4.4.21-64-default (jupiter)         10/12/16        _x86_64_        (2 CPU)

17:51:29        CPU     %user     %nice   %system   %iowait    %steal     %idle
17:51:39        all     57,93      0,00      9,58      1,01      0,00     31,47
17:51:49        all     32,71      0,00      3,79      0,05      0,00     63,45
17:51:59        all     47,23      0,00      3,66      0,00      0,00     49,11
17:52:09        all     53,33      0,00      4,88      0,05      0,00     41,74
17:52:19        all     56,98      0,00      5,65      0,10      0,00     37,27
Average:        all     49,62      0,00      5,51      0,24      0,00     44,62

%iowait displays the percentage of time that the CPU was idle while waiting for an I/O request. If this value is significantly higher than zero over a longer time, there is a bottleneck in the I/O system (network or hard disk). If the %idle value is zero over a longer time, your CPU is working at capacity.

2.1.3.1.2 Memory Usage Report: sar -r

Generate an overall picture of the system memory (RAM) by using the option -r:

root # sar -r 10 5
Linux 4.4.21-64-default (jupiter)         10/12/16        _x86_64_        (2 CPU)

17:55:27 kbmemfree kbmemused %memused kbbuffers kbcached kbcommit %commit kbactive kbinact kbdirty
17:55:37    104232   1834624    94.62        20   627340  2677656   66.24   802052  828024    1744
17:55:47     98584   1840272    94.92        20   624536  2693936   66.65   808872  826932    2012
17:55:57     87088   1851768    95.51        20   605288  2706392   66.95   827260  821304    1588
17:56:07     86268   1852588    95.55        20   599240  2739224   67.77   829764  820888    3036
17:56:17    104260   1834596    94.62        20   599864  2730688   67.56   811284  821584    3164
Average:     96086   1842770    95.04        20   611254  2709579   67.03   815846  823746    2309

The columns kbcommit and %commit show an approximation of the maximum amount of memory (RAM and swap) that the current workload could need. While kbcommit displays the absolute number in kilobytes, %commit displays a percentage.

2.1.3.1.3 Paging Statistics Report: sar -B

Use the option -B to display the kernel paging statistics.

root # sar -B 10 5
Linux 4.4.21-64-default (jupiter)         10/12/16        _x86_64_        (2 CPU)

18:23:01 pgpgin/s pgpgout/s fault/s majflt/s pgfree/s pgscank/s pgscand/s pgsteal/s %vmeff
18:23:11   366.80     11.60  542.50     1.10  4354.80      0.00      0.00      0.00   0.00
18:23:21     0.00    333.30 1522.40     0.00 18132.40      0.00      0.00      0.00   0.00
18:23:31    47.20    127.40 1048.30     0.10 11887.30      0.00      0.00      0.00   0.00
18:23:41    46.40      2.50  336.10     0.10  7945.00      0.00      0.00      0.00   0.00
18:23:51     0.00    583.70 2037.20     0.00 17731.90      0.00      0.00      0.00   0.00
Average:    92.08    211.70 1097.30     0.26 12010.28      0.00      0.00      0.00   0.00

The majflt/s (major faults per second) column shows how many pages are loaded from disk into memory. The source of the faults may be file accesses or faults. At times, many major faults are normal. For example, during application start-up time. If major faults are experienced for the entire lifetime of the application it may be an indication that there is insufficient main memory, particularly if combined with large amounts of direct scanning (pgscand/s).

The %vmeff column shows the number of pages scanned (pgscand/s) in relation to the ones being reused from the main memory cache or the swap cache (pgsteal/s). It is a measurement of the efficiency of page reclaim. Healthy values are either near 100 (every inactive page swapped out is being reused) or 0 (no pages have been scanned). The value should not drop below 30.

2.1.3.1.4 Block Device Statistics Report: sar -d

Use the option -d to display the block device (hard disk, optical drive, USB storage device, etc.). Make sure to use the additional option -p (pretty-print) to make the DEV column readable.

root # sar -d -p 10 5
 Linux 4.4.21-64-default (jupiter)         10/12/16        _x86_64_        (2 CPU)

18:46:09 DEV   tps rd_sec/s  wr_sec/s  avgrq-sz  avgqu-sz     await     svctm     %util
18:46:19 sda  1.70    33.60      0.00     19.76      0.00      0.47      0.47      0.08
18:46:19 sr0  0.00     0.00      0.00      0.00      0.00      0.00      0.00      0.00

18:46:19 DEV   tps rd_sec/s  wr_sec/s  avgrq-sz  avgqu-sz     await     svctm     %util
18:46:29 sda  8.60   114.40    518.10     73.55      0.06      7.12      0.93      0.80
18:46:29 sr0  0.00     0.00      0.00      0.00      0.00      0.00      0.00      0.00

18:46:29 DEV   tps rd_sec/s  wr_sec/s  avgrq-sz  avgqu-sz     await     svctm     %util
18:46:39 sda 40.50  3800.80    454.90    105.08      0.36      8.86      0.69      2.80
18:46:39 sr0  0.00     0.00      0.00      0.00      0.00      0.00      0.00      0.00

18:46:39 DEV   tps rd_sec/s  wr_sec/s  avgrq-sz  avgqu-sz     await     svctm     %util
18:46:49 sda  1.40     0.00    204.90    146.36      0.00      0.29      0.29      0.04
18:46:49 sr0  0.00     0.00      0.00      0.00      0.00      0.00      0.00      0.00

18:46:49 DEV   tps rd_sec/s  wr_sec/s  avgrq-sz  avgqu-sz     await     svctm     %util
18:46:59 sda  3.30     0.00    503.80    152.67      0.03      8.12      1.70      0.56
18:46:59 sr0  0.00     0.00      0.00      0.00      0.00      0.00      0.00      0.00

Average: DEV   tps rd_sec/s  wr_sec/s  avgrq-sz  avgqu-sz     await     svctm     %util
Average: sda 11.10   789.76    336.34    101.45      0.09      8.07      0.77      0.86
Average: sr0  0.00     0.00      0.00      0.00      0.00      0.00      0.00      0.00

Compare the Average values for tps, rd_sec/s, and wr_sec/s of all disks. Constantly high values in the svctm and %util columns could be an indication that I/O subsystem is a bottleneck.

If the machine uses multiple disks, then it is best if I/O is interleaved evenly between disks of equal speed and capacity. It will be necessary to take into account whether the storage has multiple tiers. Furthermore, if there are multiple paths to storage then consider what the link saturation will be when balancing how storage is used.

2.1.3.1.5 Network Statistics Reports: sar -n KEYWORD

The option -n lets you generate multiple network related reports. Specify one of the following keywords along with the -n:

  • DEV: Generates a statistic report for all network devices

  • EDEV: Generates an error statistics report for all network devices

  • NFS: Generates a statistic report for an NFS client

  • NFSD: Generates a statistic report for an NFS server

  • SOCK: Generates a statistic report on sockets

  • ALL: Generates all network statistic reports

2.1.3.2 Visualizing sar Data

sar reports are not always easy to parse for humans. kSar, a Java application visualizing your sar data, creates easy-to-read graphs. It can even generate PDF reports. kSar takes data generated on the fly and past data from a file. kSar is licensed under the BSD license and is available from https://sourceforge.net/projects/ksar/.

2.2 System Information

2.2.1 Device Load Information: iostat

To monitor the system device load, use iostat. It generates reports that can be useful for better balancing the load between physical disks attached to your system.

To be able to use iostat, install the package sysstat.

The first iostat report shows statistics collected since the system was booted. Subsequent reports cover the time since the previous report.

tux > iostat
Linux 4.4.21-64-default (jupiter)         10/12/16        _x86_64_        (4 CPU)

avg-cpu:  %user   %nice %system %iowait  %steal   %idle
          17.68    4.49    4.24    0.29    0.00   73.31

Device:            tps    kB_read/s    kB_wrtn/s    kB_read    kB_wrtn
sdb               2.02        36.74        45.73    3544894    4412392
sda               1.05         5.12        13.47     493753    1300276
sdc               0.02         0.14         0.00      13641         37

Invoking iostat in this way will help you find out whether throughput is different from your expectation, but not why. Such questions can be better answered by an extended report which can be generated by invoking iostat -x. Extended reports additionally include, for example, information on average queue sizes and average wait times. It may also be easier to evaluate the data if idle block devices are excluded using the -z switch. Find definitions for each of the displayed column titles in the man page of iostat (man 1 iostat).

You can also specify that a certain device should be monitored at specified intervals. For example, to generate five reports at three-second intervals for the device sda, use:

tux > iostat -p sda 3 5

To show statistics of network file systems (NFS), there are two similar utilities:

  • nfsiostat-sysstat is included with the package sysstat.

  • nfsiostat is included with the package nfs-client.

2.2.2 Processor Activity Monitoring: mpstat

The utility mpstat examines activities of each available processor. If your system has one processor only, the global average statistics will be reported.

The timing arguments work the same way as with the iostat command. Entering mpstat 2 5 prints five reports for all processors in two-second intervals.

root # mpstat 2 5
Linux 4.4.21-64-default (jupiter)         10/12/16        _x86_64_        (2 CPU)

13:51:10  CPU   %usr  %nice  %sys  %iowait  %irq  %soft  %steal  %guest  %gnice   %idle
13:51:12  all   8,27   0,00  0,50     0,00  0,00   0,00    0,00    0,00    0,00   91,23
13:51:14  all  46,62   0,00  3,01     0,00  0,00   0,25    0,00    0,00    0,00   50,13
13:51:16  all  54,71   0,00  3,82     0,00  0,00   0,51    0,00    0,00    0,00   40,97
13:51:18  all  78,77   0,00  5,12     0,00  0,00   0,77    0,00    0,00    0,00   15,35
13:51:20  all  51,65   0,00  4,30     0,00  0,00   0,51    0,00    0,00    0,00   43,54
Average:  all  47,85   0,00  3,34     0,00  0,00   0,40    0,00    0,00    0,00   48,41

From the mpstat data, you can see:

  • The ratio between the %usr and %sys. For example, a ratio of 10:1 indicates the workload is mostly running application code and analysis should focus on the application. A ratio of 1:10 indicates the workload is mostly kernel-bound and tuning the kernel is worth considering. Alternatively, determine why the application is kernel-bound and see if that can be alleviated.

  • Whether there is a subset of CPUs that are nearly fully utilized even if the system is lightly loaded overall. Few hot CPUs can indicate that the workload is not parallelized and could benefit from executing on a machine with a smaller number of faster processors.

2.2.3 Processor Frequency Monitoring: turbostat

turbostat shows frequencies, load, temperature, and power of AMD64/Intel 64 processors. It can operate in two modes: If called with a command, the command process is forked and statistics are displayed upon command completion. When run without a command, it will display updated statistics every five seconds. Note that turbostat requires the kernel module msr to be loaded.

tux > sudo turbostat find /etc -type d -exec true {} \;
0.546880 sec
     CPU Avg_MHz   Busy% Bzy_MHz TSC_MHz
       -     416   28.43    1465    3215
       0     631   37.29    1691    3215
       1     416   27.14    1534    3215
       2     270   24.30    1113    3215
       3     406   26.57    1530    3214
       4     505   32.46    1556    3214
       5     270   22.79    1184    3214

The output depends on the CPU type and may vary. To display more details such as temperature and power, use the --debug option. For more command line options and an explanation of the field descriptions, refer to man 8 turbostat.

2.2.4 Task Monitoring: pidstat

If you need to see what load a particular task applies to your system, use pidstat command. It prints activity of every selected task or all tasks managed by Linux kernel if no task is specified. You can also set the number of reports to be displayed and the time interval between them.

For example, pidstat -C firefox 2 3 prints the load statistic for tasks whose command name includes the string firefox. There will be three reports printed at two second intervals.

root # pidstat -C firefox 2 3
Linux 4.4.21-64-default (jupiter)         10/12/16        _x86_64_        (2 CPU)

14:09:11      UID       PID    %usr %system  %guest    %CPU   CPU  Command
14:09:13     1000       387   22,77    0,99    0,00   23,76     1  firefox

14:09:13      UID       PID    %usr %system  %guest    %CPU   CPU  Command
14:09:15     1000       387   46,50    3,00    0,00   49,50     1  firefox

14:09:15      UID       PID    %usr %system  %guest    %CPU   CPU  Command
14:09:17     1000       387   60,50    7,00    0,00   67,50     1  firefox

Average:      UID       PID    %usr %system  %guest    %CPU   CPU  Command
Average:     1000       387   43,19    3,65    0,00   46,84     -  firefox

Similarly, pidstat -d can be used to estimate how much I/O tasks are doing, whether they are sleeping on that I/O and how many clock ticks the task was stalled.

2.2.5 Kernel Ring Buffer: dmesg

The Linux kernel keeps certain messages in a ring buffer. To view these messages, enter the command dmesg -T.

Older events are logged in the systemd journal. See Chapter 15, journalctl: Query the systemd Journal for more information on the journal.

2.2.6 List of Open Files: lsof

To view a list of all the files open for the process with process ID PID, use -p. For example, to view all the files used by the current shell, enter:

root # lsof -p $$
COMMAND  PID USER   FD   TYPE DEVICE SIZE/OFF  NODE NAME
bash    8842 root  cwd    DIR   0,32      222  6772 /root
bash    8842 root  rtd    DIR   0,32      166   256 /
bash    8842 root  txt    REG   0,32   656584 31066 /bin/bash
bash    8842 root  mem    REG   0,32  1978832 22993 /lib64/libc-2.19.so
[...]
bash    8842 root    2u   CHR  136,2      0t0     5 /dev/pts/2
bash    8842 root  255u   CHR  136,2      0t0     5 /dev/pts/2

The special shell variable $$, whose value is the process ID of the shell, has been used.

When used with -i, lsof lists currently open Internet files as well:

root # lsof -i
COMMAND    PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
wickedd-d  917 root    8u  IPv4  16627      0t0  UDP *:bootpc
wickedd-d  918 root    8u  IPv6  20752      0t0  UDP [fe80::5054:ff:fe72:5ead]:dhcpv6-client
sshd      3152 root    3u  IPv4  18618      0t0  TCP *:ssh (LISTEN)
sshd      3152 root    4u  IPv6  18620      0t0  TCP *:ssh (LISTEN)
master    4746 root   13u  IPv4  20588      0t0  TCP localhost:smtp (LISTEN)
master    4746 root   14u  IPv6  20589      0t0  TCP localhost:smtp (LISTEN)
sshd      8837 root    5u  IPv4 293709      0t0  TCP jupiter.suse.de:ssh->venus.suse.de:33619 (ESTABLISHED)
sshd      8837 root    9u  IPv6 294830      0t0  TCP localhost:x11 (LISTEN)
sshd      8837 root   10u  IPv4 294831      0t0  TCP localhost:x11 (LISTEN)

2.2.7 Kernel and udev Event Sequence Viewer: udevadm monitor

udevadm monitor listens to the kernel uevents and events sent out by a udev rule and prints the device path (DEVPATH) of the event to the console. This is a sequence of events while connecting a USB memory stick:

Note
Note: Monitoring udev Events

Only root user is allowed to monitor udev events by running the udevadm command.

UEVENT[1138806687] add@/devices/pci0000:00/0000:00:1d.7/usb4/4-2/4-2.2
UEVENT[1138806687] add@/devices/pci0000:00/0000:00:1d.7/usb4/4-2/4-2.2/4-2.2
UEVENT[1138806687] add@/class/scsi_host/host4
UEVENT[1138806687] add@/class/usb_device/usbdev4.10
UDEV  [1138806687] add@/devices/pci0000:00/0000:00:1d.7/usb4/4-2/4-2.2
UDEV  [1138806687] add@/devices/pci0000:00/0000:00:1d.7/usb4/4-2/4-2.2/4-2.2
UDEV  [1138806687] add@/class/scsi_host/host4
UDEV  [1138806687] add@/class/usb_device/usbdev4.10
UEVENT[1138806692] add@/devices/pci0000:00/0000:00:1d.7/usb4/4-2/4-2.2/4-2.2
UEVENT[1138806692] add@/block/sdb
UEVENT[1138806692] add@/class/scsi_generic/sg1
UEVENT[1138806692] add@/class/scsi_device/4:0:0:0
UDEV  [1138806693] add@/devices/pci0000:00/0000:00:1d.7/usb4/4-2/4-2.2/4-2.2
UDEV  [1138806693] add@/class/scsi_generic/sg1
UDEV  [1138806693] add@/class/scsi_device/4:0:0:0
UDEV  [1138806693] add@/block/sdb
UEVENT[1138806694] add@/block/sdb/sdb1
UDEV  [1138806694] add@/block/sdb/sdb1
UEVENT[1138806694] mount@/block/sdb/sdb1
UEVENT[1138806697] umount@/block/sdb/sdb1

2.3 Processes

2.3.1 Interprocess Communication: ipcs

The command ipcs produces a list of the IPC resources currently in use:

root # ipcs
------ Message Queues --------
key        msqid      owner      perms      used-bytes   messages

------ Shared Memory Segments --------
key        shmid      owner      perms      bytes      nattch     status
0x00000000 65536      tux        600        524288     2          dest
0x00000000 98305      tux        600        4194304    2          dest
0x00000000 884738     root       600        524288     2          dest
0x00000000 786435     tux        600        4194304    2          dest
0x00000000 12058628   tux        600        524288     2          dest
0x00000000 917509     root       600        524288     2          dest
0x00000000 12353542   tux        600        196608     2          dest
0x00000000 12451847   tux        600        524288     2          dest
0x00000000 11567114   root       600        262144     1          dest
0x00000000 10911763   tux        600        2097152    2          dest
0x00000000 11665429   root       600        2336768    2          dest
0x00000000 11698198   root       600        196608     2          dest
0x00000000 11730967   root       600        524288     2          dest

------ Semaphore Arrays --------
key        semid      owner      perms      nsems
0xa12e0919 32768      tux        666        2

2.3.2 Process List: ps

The command ps produces a list of processes. Most parameters must be written without a minus sign. Refer to ps --help for a brief help or to the man page for extensive help.

To list all processes with user and command line information, use ps axu:

tux > ps axu
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.0  0.3  34376  4608 ?        Ss   Jul24   0:02 /usr/lib/systemd/systemd
root         2  0.0  0.0      0     0 ?        S    Jul24   0:00 [kthreadd]
root         3  0.0  0.0      0     0 ?        S    Jul24   0:00 [ksoftirqd/0]
root         5  0.0  0.0      0     0 ?        S<   Jul24   0:00 [kworker/0:0H]
root         6  0.0  0.0      0     0 ?        S    Jul24   0:00 [kworker/u2:0]
root         7  0.0  0.0      0     0 ?        S    Jul24   0:00 [migration/0]
[...]
tux      12583  0.0  0.1 185980  2720 ?        Sl   10:12   0:00 /usr/lib/gvfs/gvfs-mtp-volume-monitor
tux      12587  0.0  0.1 198132  3044 ?        Sl   10:12   0:00 /usr/lib/gvfs/gvfs-gphoto2-volume-monitor
tux      12591  0.0  0.1 181940  2700 ?        Sl   10:12   0:00 /usr/lib/gvfs/gvfs-goa-volume-monitor
tux      12594  8.1 10.6 1418216 163564 ?      Sl   10:12   0:03 /usr/bin/gnome-shell
tux      12600  0.0  0.3 393448  5972 ?        Sl   10:12   0:00 /usr/lib/gnome-settings-daemon-3.0/gsd-printer
tux      12625  0.0  0.6 227776 10112 ?        Sl   10:12   0:00 /usr/lib/gnome-control-center-search-provider
tux      12626  0.5  1.5 890972 23540 ?        Sl   10:12   0:00 /usr/bin/nautilus --no-default-window
[...]

To check how many sshd processes are running, use the option -p together with the command pidof, which lists the process IDs of the given processes.

tux > ps -p $(pidof sshd)
  PID TTY      STAT   TIME COMMAND
 1545 ?        Ss     0:00 /usr/sbin/sshd -D
 4608 ?        Ss     0:00 sshd: root@pts/0

The process list can be formatted according to your needs. The option L returns a list of all keywords. Enter the following command to issue a list of all processes sorted by memory usage:

tux > ps ax --format pid,rss,cmd --sort rss
  PID   RSS CMD
  PID   RSS CMD
    2     0 [kthreadd]
    3     0 [ksoftirqd/0]
    4     0 [kworker/0:0]
    5     0 [kworker/0:0H]
    6     0 [kworker/u2:0]
    7     0 [migration/0]
    8     0 [rcu_bh]
[...]
12518 22996 /usr/lib/gnome-settings-daemon-3.0/gnome-settings-daemon
12626 23540 /usr/bin/nautilus --no-default-window
12305 32188 /usr/bin/Xorg :0 -background none -verbose
12594 164900 /usr/bin/gnome-shell
Useful ps Calls
ps aux--sort COLUMN

Sort the output by COLUMN. Replace COLUMN with

pmem for physical memory ratio
pcpu for CPU ratio
rss for resident set size (non-swapped physical memory)
ps axo pid,%cpu,rss,vsz,args,wchan

Shows every process, their PID, CPU usage ratio, memory size (resident and virtual), name, and their syscall.

ps axfo pid,args

Show a process tree.

2.3.3 Process Tree: pstree

The command pstree produces a list of processes in the form of a tree:

tux > pstree
systemd---accounts-daemon---{gdbus}
        |                 |-{gmain}
        |-at-spi-bus-laun---dbus-daemon
        |                 |-{dconf worker}
        |                 |-{gdbus}
        |                 |-{gmain}
        |-at-spi2-registr---{gdbus}
        |-cron
        |-2*[dbus-daemon]
        |-dbus-launch
        |-dconf-service---{gdbus}
        |               |-{gmain}
        |-gconfd-2
        |-gdm---gdm-simple-slav---Xorg
        |     |                 |-gdm-session-wor---gnome-session---gnome-setti+
        |     |                 |                 |               |-gnome-shell+++
        |     |                 |                 |               |-{dconf work+
        |     |                 |                 |               |-{gdbus}
        |     |                 |                 |               |-{gmain}
        |     |                 |                 |-{gdbus}
        |     |                 |                 |-{gmain}
        |     |                 |-{gdbus}
        |     |                 |-{gmain}
        |     |-{gdbus}
        |     |-{gmain}
[...]

The parameter -p adds the process ID to a given name. To have the command lines displayed as well, use the -a parameter:

2.3.4 Table of Processes: top

The command top (an abbreviation of table of processes) displays a list of processes that is refreshed every two seconds. To terminate the program, press Q. The parameter -n 1 terminates the program after a single display of the process list. The following is an example output of the command top -n 1:

tux > top -n 1
Tasks: 128 total,   1 running, 127 sleeping,   0 stopped,   0 zombie
%Cpu(s):  2.4 us,  1.2 sy,  0.0 ni, 96.3 id,  0.1 wa,  0.0 hi,  0.0 si,  0.0 st
KiB Mem:   1535508 total,   699948 used,   835560 free,      880 buffers
KiB Swap:  1541116 total,        0 used,  1541116 free.   377000 cached Mem

  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
    1 root      20   0  116292   4660   2028 S 0.000 0.303   0:04.45 systemd
    2 root      20   0       0      0      0 S 0.000 0.000   0:00.00 kthreadd
    3 root      20   0       0      0      0 S 0.000 0.000   0:00.07 ksoftirqd+
    5 root       0 -20       0      0      0 S 0.000 0.000   0:00.00 kworker/0+
    6 root      20   0       0      0      0 S 0.000 0.000   0:00.00 kworker/u+
    7 root      rt   0       0      0      0 S 0.000 0.000   0:00.00 migration+
    8 root      20   0       0      0      0 S 0.000 0.000   0:00.00 rcu_bh
    9 root      20   0       0      0      0 S 0.000 0.000   0:00.24 rcu_sched
   10 root      rt   0       0      0      0 S 0.000 0.000   0:00.01 watchdog/0
   11 root       0 -20       0      0      0 S 0.000 0.000   0:00.00 khelper
   12 root      20   0       0      0      0 S 0.000 0.000   0:00.00 kdevtmpfs
   13 root       0 -20       0      0      0 S 0.000 0.000   0:00.00 netns
   14 root       0 -20       0      0      0 S 0.000 0.000   0:00.00 writeback
   15 root       0 -20       0      0      0 S 0.000 0.000   0:00.00 kintegrit+
   16 root       0 -20       0      0      0 S 0.000 0.000   0:00.00 bioset
   17 root       0 -20       0      0      0 S 0.000 0.000   0:00.00 crypto
   18 root       0 -20       0      0      0 S 0.000 0.000   0:00.00 kblockd

By default the output is sorted by CPU usage (column %CPU, shortcut ShiftP). Use the following key combinations to change the sort field:

ShiftM: Resident Memory (RES)
ShiftN: Process ID (PID)
ShiftT: Time (TIME+)

To use any other field for sorting, press F and select a field from the list. To toggle the sort order, Use ShiftR.

The parameter -U UID monitors only the processes associated with a particular user. Replace UID with the user ID of the user. Use top -U $(id -u) to show processes of the current user

2.3.5 z Systems Hypervisor Monitor: hyptop

hyptop provides a dynamic real-time view of a z Systems hypervisor environment, using the kernel infrastructure via debugfs. It works with either the z/VM or the LPAR hypervisor. Depending on the available data it, for example, shows CPU and memory consumption of active LPARs or z/VM guests. It provides a curses based user interface similar to the top command. hyptop provides two windows:

  • sys_list: Lists systems that the currently hypervisor is running

  • sys: Shows one system in more detail

You can run hyptop in interactive mode (default) or in batch mode with the -b option. Help in the interactive mode is available by pressing ? after hyptop is started.

Output for the sys_list window under LPAR:

12:30:48 | CPU-T: IFL(18) CP(3) UN(3)     ?=help
system  #cpu    cpu   mgm    Cpu+  Mgm+   online
(str)    (#)    (%)   (%)    (hm)  (hm)    (dhm)
H05LP30   10 461.14 10.18 1547:41  8:15 11:05:59
H05LP33    4 133.73  7.57  220:53  6:12 11:05:54
H05LP50    4  99.26  0.01  146:24  0:12 10:04:24
H05LP02    1  99.09  0.00  269:57  0:00 11:05:58
TRX2CFA    1   2.14  0.03    3:24  0:04 11:06:01
H05LP13    6   1.36  0.34    4:23  0:54 11:05:56
TRX1      19   1.22  0.14   13:57  0:22 11:06:01
TRX2      20   1.16  0.11   26:05  0:25 11:06:00
H05LP55    2   0.00  0.00    0:22  0:00 11:05:52
H05LP56    3   0.00  0.00    0:00  0:00 11:05:52
         413 823.39 23.86 3159:57 38:08 11:06:01

Output for the "sys_list" window under z/VM:

12:32:21 | CPU-T: UN(16)                          ?=help
system   #cpu    cpu    Cpu+   online memuse memmax wcur
(str)     (#)    (%)    (hm)    (dhm)  (GiB)  (GiB)  (#)
T6360004    6 100.31  959:47 53:05:20   1.56   2.00  100
T6360005    2   0.44    1:11  3:02:26   0.42   0.50  100
T6360014    2   0.27    0:45 10:18:41   0.54   0.75  100
DTCVSW1     1   0.00    0:00 53:16:42   0.01   0.03  100
T6360002    6   0.00  166:26 40:19:18   1.87   2.00  100
OPERATOR    1   0.00    0:00 53:16:42   0.00   0.03  100
T6360008    2   0.00    0:37 30:22:55   0.32   0.75  100
T6360003    6   0.00 3700:57 53:03:09   4.00   4.00  100
NSLCF1      1   0.00    0:02 53:16:41   0.03   0.25  500
EREP        1   0.00    0:00 53:16:42   0.00   0.03  100
PERFSVM     1   0.00    0:53  2:21:12   0.04   0.06    0
TCPIP       1   0.00    0:01 53:16:42   0.01   0.12 3000
DATAMOVE    1   0.00    0:05 53:16:42   0.00   0.03  100
DIRMAINT    1   0.00    0:04 53:16:42   0.01   0.03  100
DTCVSW2     1   0.00    0:00 53:16:42   0.01   0.03  100
RACFVM      1   0.00    0:00 53:16:42   0.01   0.02  100
           75 101.57 5239:47 53:16:42  15.46  22.50 3000

Output for the sys window under LPAR:

14:08:41 | H05LP30 | CPU-T: IFL(18) CP(3) UN(3)                  ? = help
cpuid   type    cpu   mgm visual.
(#)    (str)    (%)   (%) (vis)
0        IFL  96.91  1.96 |############################################ |
1        IFL  81.82  1.46 |#####################################        |
2        IFL  88.00  2.43 |########################################     |
3        IFL  92.27  1.29 |##########################################   |
4        IFL  83.32  1.05 |#####################################        |
5        IFL  92.46  2.59 |##########################################   |
6        IFL   0.00  0.00 |                                             |
7        IFL   0.00  0.00 |                                             |
8        IFL   0.00  0.00 |                                             |
9        IFL   0.00  0.00 |                                             |
             534.79 10.78

Output for the sys window under z/VM:

15:46:57 | T6360003 | CPU-T: UN(16)                  ? = help
cpuid     cpu visual
(#)       (%) (vis)
0      548.72 |#########################################    |
        548.72

2.3.6 A top-like I/O Monitor: iotop

The iotop utility displays a table of I/O usage by processes or threads.

Note
Note: Installing iotop

iotop is not installed by default. You need to install it manually with zypper in iotop as root.

iotop displays columns for the I/O bandwidth read and written by each process during the sampling period. It also displays the percentage of time the process spent while swapping in and while waiting on I/O. For each process, its I/O priority (class/level) is shown. In addition, the total I/O bandwidth read and written during the sampling period is displayed at the top of the interface.

  • The and keys change the sorting.

  • R reverses the sort order.

  • O toggles between showing all processes and threads (default view) and showing only those doing I/O. (This function is similar to adding --only on command line.)

  • P toggles between showing threads (default view) and processes. (This function is similar to --only.)

  • A toggles between showing the current I/O bandwidth (default view) and accumulated I/O operations since iotop was started. (This function is similar to --accumulated.)

  • I lets you change the priority of a thread or a process's threads.

  • Q quits iotop.

  • Pressing any other key will force a refresh.

Following is an example output of the command iotop --only, while find and emacs are running:

root # iotop --only
Total DISK READ: 50.61 K/s | Total DISK WRITE: 11.68 K/s
  TID  PRIO  USER     DISK READ  DISK WRITE  SWAPIN     IO>    COMMAND
 3416 be/4 tux         50.61 K/s    0.00 B/s  0.00 %  4.05 % find /
  275 be/3 root        0.00 B/s    3.89 K/s  0.00 %  2.34 % [jbd2/sda2-8]
 5055 be/4 tux          0.00 B/s    3.89 K/s  0.00 %  0.04 % emacs

iotop can be also used in a batch mode (-b) and its output stored in a file for later analysis. For a complete set of options, see the manual page (man 8 iotop).

2.3.7 Modify a process's niceness: nice and renice

The kernel determines which processes require more CPU time than others by the process's nice level, also called niceness. The higher the nice level of a process is, the less CPU time it will take from other processes. Nice levels range from -20 (the least nice level) to 19. Negative values can only be set by root.

Adjusting the niceness level is useful when running a non time-critical process that lasts long and uses large amounts of CPU time. For example, compiling a kernel on a system that also performs other tasks. Making such a process nicer, ensures that the other tasks, for example a Web server, will have a higher priority.

Calling nice without any parameters prints the current niceness:

tux > nice
0

Running nice COMMAND increments the current nice level for the given command by 10. Using nice -n LEVEL COMMAND lets you specify a new niceness relative to the current one.

To change the niceness of a running process, use renice PRIORITY -p PROCESS_ID, for example:

tux > renice +5 3266

To renice all processes owned by a specific user, use the option -u USER. Process groups are reniced by the option -g PROCESS_GROUP_ID.

2.4 Memory

2.4.1 Memory Usage: free

The utility free examines RAM and swap usage. Details of both free and used memory and swap areas are shown:

tux > free
             total       used       free     shared    buffers     cached
Mem:      32900500   32703448     197052          0     255668    5787364
-/+ buffers/cache:   26660416    6240084
Swap:      2046972     304680    1742292

The options -b, -k, -m, -g show the output in bytes, KB, MB, or GB, respectively. The parameter -s delay ensures that the display is refreshed every DELAY seconds. For example, free -s 1.5 produces an update every 1.5 seconds.

2.4.2 Detailed Memory Usage: /proc/meminfo

Use /proc/meminfo to get more detailed information on memory usage than with free. Actually free uses some data from this file. See an example output from a 64-bit system below. Note that it slightly differs on 32-bit systems because of different memory management:

MemTotal:        1942636 kB
MemFree:         1294352 kB
MemAvailable:    1458744 kB
Buffers:             876 kB
Cached:           278476 kB
SwapCached:            0 kB
Active:           368328 kB
Inactive:         199368 kB
Active(anon):     288968 kB
Inactive(anon):    10568 kB
Active(file):      79360 kB
Inactive(file):   188800 kB
Unevictable:          80 kB
Mlocked:              80 kB
SwapTotal:       2103292 kB
SwapFree:        2103292 kB
Dirty:                44 kB
Writeback:             0 kB
AnonPages:        288592 kB
Mapped:            70444 kB
Shmem:             11192 kB
Slab:              40916 kB
SReclaimable:      17712 kB
SUnreclaim:        23204 kB
KernelStack:        2000 kB
PageTables:        10996 kB
NFS_Unstable:          0 kB
Bounce:                0 kB
WritebackTmp:          0 kB
CommitLimit:     3074608 kB
Committed_AS:    1407208 kB
VmallocTotal:   34359738367 kB
VmallocUsed:      145996 kB
VmallocChunk:   34359588844 kB
HardwareCorrupted:     0 kB
AnonHugePages:     86016 kB
HugePages_Total:       0
HugePages_Free:        0
HugePages_Rsvd:        0
HugePages_Surp:        0
Hugepagesize:       2048 kB
DirectMap4k:       79744 kB
DirectMap2M:     2017280 kB

These entries stand for the following:

MemTotal

Total amount of RAM.

MemFree

Amount of unused RAM.

MemAvailable

Estimate of how much memory is available for starting new applications without swapping.

Buffers

File buffer cache in RAM containing file system metadata.

Cached

Page cache in RAM. This excludes buffer cache and swap cache, but includes Shmem memory.

SwapCached

Page cache for swapped-out memory.

Active, Active(anon), Active(file)

Recently used memory that will not be reclaimed unless necessary or on explicit request. Active is the sum of Active(anon) and Active(file):

  • Active(anon) tracks swap-backed memory. This includes private and shared anonymous mappings and private file pages after copy-on-write.

  • Active(file) tracks other file system backed memory.

Inactive, Inactive(anon), Inactive(file)

Less recently used memory that will usually be reclaimed first. Inactive is the sum of Inactive(anon) and Inactive(file):

  • Inactive(anon) tracks swap backed memory. This includes private and shared anonymous mappings and private file pages after copy-on-write.

  • Inactive(file) tracks other file system backed memory.

Unevictable

Amount of memory that cannot be reclaimed (for example, because it is Mlocked or used as a RAM disk).

Mlocked

Amount of memory that is backed by the mlock system call. mlock allows processes to define which part of physical RAM their virtual memory should be mapped to. However, mlock does not guarantee this placement.

SwapTotal

Amount of swap space.

SwapFree

Amount of unused swap space.

Dirty

Amount of memory waiting to be written to disk, because it contains changes compared to the backing storage. Dirty data can be explicitly synchronized either by the application or by the kernel after a short delay. A large amount of dirty data may take considerable time to write to disk resulting in stalls. The total amount of dirty data that can exist at any time can be controlled with the sysctl parameters vm.dirty_ratio or vm.dirty_bytes (refer to Section 14.1.5, “Writeback” for more details).

Writeback

Amount of memory that is currently being written to disk.

Mapped

Memory claimed with the mmap system call.

Shmem

Memory shared between groups of processes, such as IPC data, tmpfs data, and shared anonymous memory.

Slab

Memory allocation for internal data structures of the kernel.

SReclaimable

Slab section that can be reclaimed, such as caches (inode, dentry, etc.).

SUnreclaim

Slab section that cannot be reclaimed.

KernelStack

Amount of kernel space memory used by applications (through system calls).

PageTables

Amount of memory dedicated to page tables of all processes.

NFS_Unstable

NFS pages that have already been sent to the server, but are not yet committed there.

Bounce

Memory used for bounce buffers of block devices.

WritebackTmp

Memory used by FUSE for temporary writeback buffers.

CommitLimit

Amount of memory available to the system based on the overcommit ratio setting. This is only enforced if strict overcommit accounting is enabled.

Committed_AS

An approximation of the total amount of memory (RAM and swap) that the current workload would need in the worst case.

VmallocTotal

Amount of allocated kernel virtual address space.

VmallocUsed

Amount of used kernel virtual address space.

VmallocChunk

The largest contiguous block of available kernel virtual address space.

HardwareCorrupted

Amount of failed memory (can only be detected when using ECC RAM).

AnonHugePages

Anonymous hugepages that are mapped into user space page tables. These are allocated transparently for processes without being specifically requested, therefore they are also known as transparent hugepages (THP).

HugePages_Total

Number of preallocated hugepages for use by SHM_HUGETLB and MAP_HUGETLB or through the hugetlbfs file system, as defined in /proc/sys/vm/nr_hugepages.

HugePages_Free

Number of hugepages available.

HugePages_Rsvd

Number of hugepages that are committed.

HugePages_Surp

Number of hugepages available beyond HugePages_Total (surplus), as defined in /proc/sys/vm/nr_overcommit_hugepages.

Hugepagesize

Size of a hugepage—on AMD64/Intel 64 the default is 2048 KB.

DirectMap4k etc.

Amount of kernel memory that is mapped to pages with a given size (in the example: 4 kB).

2.4.3 Process Memory Usage: smaps

Exactly determining how much memory a certain process is consuming is not possible with standard tools like top or ps. Use the smaps subsystem, introduced in kernel 2.6.14, if you need exact data. It can be found at /proc/PID/smaps and shows you the number of clean and dirty memory pages the process with the ID PID is using at that time. It differentiates between shared and private memory, so you can see how much memory the process is using without including memory shared with other processes. For more information see /usr/src/linux/Documentation/filesystems/proc.txt (requires the package kernel-source to be installed).

smaps is expensive to read. Therefore it is not recommended to monitor it regularly, but only when closely monitoring a certain process.

2.5 Networking

Tip
Tip: Traffic Shaping

In case the network bandwidth is lower than expected, you should first check if any traffic shaping rules are active for your network segment.

2.5.1 Basic Network Diagnostics: ip

ip is a powerful tool to set up and control network interfaces. You can also use it to quickly view basic statistics about network interfaces of the system. For example, whether the interface is up or how many errors, dropped packets, or packet collisions there are.

If you run ip with no additional parameter, it displays a help output. To list all network interfaces, enter ip addr show (or abbreviated as ip a). ip addr show up lists only running network interfaces. ip -s link show DEVICE lists statistics for the specified interface only:

root # ip -s link show br0
6: br0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT
    link/ether 00:19:d1:72:d4:30 brd ff:ff:ff:ff:ff:ff
    RX: bytes  packets  errors  dropped overrun mcast
    6346104756 9265517  0       10860   0       0
    TX: bytes  packets  errors  dropped carrier collsns
    3996204683 3655523  0       0       0       0

ip can also show interfaces (link), routing tables (route), and much more—refer to man 8 ip for details.

root # ip route
default via 192.168.2.1 dev eth1
192.168.2.0/24 dev eth0  proto kernel  scope link  src 192.168.2.100
192.168.2.0/24 dev eth1  proto kernel  scope link  src 192.168.2.101
192.168.2.0/24 dev eth2  proto kernel  scope link  src 192.168.2.102
root # ip link
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000
    link/ether 52:54:00:44:30:51 brd ff:ff:ff:ff:ff:ff
3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000
    link/ether 52:54:00:a3:c1:fb brd ff:ff:ff:ff:ff:ff
4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000
    link/ether 52:54:00:32:a4:09 brd ff:ff:ff:ff:ff:ff

2.5.2 Show the Network Usage of Processes: nethogs

In some cases, for example if the network traffic suddenly becomes very high, it is desirable to quickly find out which application(s) is/are causing the traffic. nethogs, a tool with a design similar to top, shows incoming and outgoing traffic for all relevant processes:

PID   USER  PROGRAM                                DEV   SENT   RECEIVED
27145 root   zypper                                eth0  5.719  391.749 KB/sec
?     root   ..0:113:80c0:8080:10:160:0:100:30015        0.102    2.326 KB/sec
26635 tux    /usr/lib64/firefox/firefox            eth0  0.026    0.026 KB/sec
?     root   ..0:113:80c0:8080:10:160:0:100:30045        0.000    0.021 KB/sec
?     root   ..0:113:80c0:8080:10:160:0:100:30045        0.000    0.018 KB/sec
?     root   ..0:113:80c0:8080:10:160:0:100:30015        0.000    0.018 KB/sec
?     root   ..0:113:80c0:8080:10:160:0:100:30045        0.000    0.017 KB/sec
?     root   ..0:113:80c0:8080:10:160:0:100:30045        0.000    0.017 KB/sec
?     root   ..0:113:80c0:8080:10:160:0:100:30045        0.069    0.000 KB/sec
?     root   unknown TCP                                 0.000    0.000 KB/sec

TOTAL                                                  5.916  394.192 KB/sec

Like in top, nethogs features interactive commands:

M: cycle between display modes (kb/s, kb, b, mb)
R: sort by RECEIVED
S: sort by SENT
Q: quit

2.5.3 Ethernet Cards in Detail: ethtool

ethtool can display and change detailed aspects of your Ethernet network device. By default it prints the current setting of the specified device.

root # ethtool eth0
Settings for eth0:
 Supported ports: [ TP ]
 Supported link modes:   10baseT/Half 10baseT/Full
                         100baseT/Half 100baseT/Full
                         1000baseT/Full
 Supports auto-negotiation: Yes
 Advertised link modes:  10baseT/Half 10baseT/Full
                         100baseT/Half 100baseT/Full
                         1000baseT/Full
 Advertised pause frame use: No
[...]
 Link detected: yes

The following table shows ethtool options that you can use to query the device for specific information:

Table 2.1: List of Query Options of ethtool

ethtool option

it queries the device for

-a

pause parameter information

-c

interrupt coalescing information

-g

Rx/Tx (receive/transmit) ring parameter information

-i

associated driver information

-k

offload information

-S

NIC and driver-specific statistics

2.5.4 Show the Network Status: ss

ss is a tool to dump socket statistics and replaces the netstat command. To list all connections use ss without parameters:

root # ss
Netid  State      Recv-Q Send-Q   Local Address:Port       Peer Address:Port
u_str  ESTAB      0      0                    * 14082                 * 14083
u_str  ESTAB      0      0                    * 18582                 * 18583
u_str  ESTAB      0      0                    * 19449                 * 19450
u_str  ESTAB      0      0      @/tmp/dbus-gmUUwXABPV 18784           * 18783
u_str  ESTAB      0      0      /var/run/dbus/system_bus_socket 19383 * 19382
u_str  ESTAB      0      0      @/tmp/dbus-gmUUwXABPV 18617           * 18616
u_str  ESTAB      0      0      @/tmp/dbus-58TPPDv8qv 19352           * 19351
u_str  ESTAB      0      0                    * 17658                 * 17657
u_str  ESTAB      0      0                    * 17693                 * 17694
[..]

To show all network ports currently open, use the following command:

root # ss -l
Netid  State      Recv-Q Send-Q      Local Address:Port  Peer Address:Port
nl     UNCONN     0      0                 rtnl:4195117                  *
nl     UNCONN     0      0       rtnl:wickedd-auto4/811                  *
nl     UNCONN     0      0       rtnl:wickedd-dhcp4/813                  *
nl     UNCONN     0      0                 rtnl:4195121                  *
nl     UNCONN     0      0                 rtnl:4195115                  *
nl     UNCONN     0      0       rtnl:wickedd-dhcp6/814                  *
nl     UNCONN     0      0                  rtnl:kernel                  *
nl     UNCONN     0      0             rtnl:wickedd/817                  *
nl     UNCONN     0      0                 rtnl:4195118                  *
nl     UNCONN     0      0                rtnl:nscd/706                  *
nl     UNCONN     4352   0              tcpdiag:ss/2381                  *
[...]

When displaying network connections, you can specify the socket type to display: TCP (-t) or UDP (-u) for example. The -p option shows the PID and name of the program to which each socket belongs.

The following example lists all TCP connections and the programs using these connections. The -a option make sure all established connections (listening and non-listening) are shown. The -p option shows the PID and name of the program to which each socket belongs.

root # ss -t -a -p
State    Recv-Q Send-Q  Local Address:Port   Peer Address:Port
LISTEN   0      128                  *:ssh                 *:*  users:(("sshd",1551,3))
LISTEN   0      100         127.0.0.1:smtp                 *:*  users:(("master",1704,13))
ESTAB    0      132      10.120.65.198:ssh  10.120.4.150:55715  users:(("sshd",2103,5))
LISTEN   0      128                 :::ssh                :::*  users:(("sshd",1551,4))
LISTEN   0      100               ::1:smtp                :::*  users:(("master",1704,14))

2.6 The /proc File System

The /proc file system is a pseudo file system in which the kernel reserves important information in the form of virtual files. For example, display the CPU type with this command:

tux > cat /proc/cpuinfo
processor       : 0
vendor_id       : GenuineIntel
cpu family      : 6
model           : 30
model name      : Intel(R) Core(TM) i5 CPU         750  @ 2.67GHz
stepping        : 5
microcode       : 0x6
cpu MHz         : 1197.000
cache size      : 8192 KB
physical id     : 0
siblings        : 4
core id         : 0
cpu cores       : 4
apicid          : 0
initial apicid  : 0
fpu             : yes
fpu_exception   : yes
cpuid level     : 11
wp              : yes
flags           : fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush dts acpi mmx fxsr sse sse2 ss ht tm pbe syscall nx rdtscp lm constant_tsc arch_perfmon pebs bts rep_good nopl xtopology nonstop_tsc aperfmperf pni dtes64 monitor ds_cpl vmx smx est tm2 ssse3 cx16 xtpr pdcm sse4_1 sse4_2 popcnt lahf_lm ida dtherm tpr_shadow vnmi flexpriority ept vpid
bogomips        : 5333.85
clflush size    : 64
cache_alignment : 64
address sizes   : 36 bits physical, 48 bits virtual
power management:
[...]
Tip
Tip: Detailed Processor Information

Detailed information about the processor on the AMD64/Intel 64 architecture is also available by running x86info.

Query the allocation and use of interrupts with the following command:

tux > cat /proc/interrupts
           CPU0       CPU1       CPU2       CPU3
  0:        121          0          0          0   IO-APIC-edge      timer
  8:          0          0          0          1   IO-APIC-edge      rtc0
  9:          0          0          0          0   IO-APIC-fasteoi   acpi
 16:          0      11933          0          0   IO-APIC-fasteoi   ehci_hcd:+
 18:          0          0          0          0   IO-APIC-fasteoi   i801_smbus
 19:          0     117978          0          0   IO-APIC-fasteoi   ata_piix,+
 22:          0          0    3275185          0   IO-APIC-fasteoi   enp5s1
 23:     417927          0          0          0   IO-APIC-fasteoi   ehci_hcd:+
 40:    2727916          0          0          0  HPET_MSI-edge      hpet2
 41:          0    2749134          0          0  HPET_MSI-edge      hpet3
 42:          0          0    2759148          0  HPET_MSI-edge      hpet4
 43:          0          0          0    2678206  HPET_MSI-edge      hpet5
 45:          0          0          0          0   PCI-MSI-edge      aerdrv, P+
 46:          0          0          0          0   PCI-MSI-edge      PCIe PME,+
 47:          0          0          0          0   PCI-MSI-edge      PCIe PME,+
 48:          0          0          0          0   PCI-MSI-edge      PCIe PME,+
 49:          0          0          0        387   PCI-MSI-edge      snd_hda_i+
 50:     933117          0          0          0   PCI-MSI-edge      nvidia
NMI:       2102       2023       2031       1920   Non-maskable interrupts
LOC:         92         71         57         41   Local timer interrupts
SPU:          0          0          0          0   Spurious interrupts
PMI:       2102       2023       2031       1920   Performance monitoring int+
IWI:      47331      45725      52464      46775   IRQ work interrupts
RTR:          2          0          0          0   APIC ICR read retries
RES:     472911     396463     339792     323820   Rescheduling interrupts
CAL:      48389      47345      54113      50478   Function call interrupts
TLB:      28410      26804      24389      26157   TLB shootdowns
TRM:          0          0          0          0   Thermal event interrupts
THR:          0          0          0          0   Threshold APIC interrupts
MCE:          0          0          0          0   Machine check exceptions
MCP:         40         40         40         40   Machine check polls
ERR:          0
MIS:          0

The address assignment of executables and libraries is contained in the maps file:

tux > cat /proc/self/maps
08048000-0804c000 r-xp 00000000 03:03 17753      /bin/cat
0804c000-0804d000 rw-p 00004000 03:03 17753      /bin/cat
0804d000-0806e000 rw-p 0804d000 00:00 0          [heap]
b7d27000-b7d5a000 r--p 00000000 03:03 11867      /usr/lib/locale/en_GB.utf8/
b7d5a000-b7e32000 r--p 00000000 03:03 11868      /usr/lib/locale/en_GB.utf8/
b7e32000-b7e33000 rw-p b7e32000 00:00 0
b7e33000-b7f45000 r-xp 00000000 03:03 8837       /lib/libc-2.3.6.so
b7f45000-b7f46000 r--p 00112000 03:03 8837       /lib/libc-2.3.6.so
b7f46000-b7f48000 rw-p 00113000 03:03 8837       /lib/libc-2.3.6.so
b7f48000-b7f4c000 rw-p b7f48000 00:00 0
b7f52000-b7f53000 r--p 00000000 03:03 11842      /usr/lib/locale/en_GB.utf8/
[...]
b7f5b000-b7f61000 r--s 00000000 03:03 9109       /usr/lib/gconv/gconv-module
b7f61000-b7f62000 r--p 00000000 03:03 9720       /usr/lib/locale/en_GB.utf8/
b7f62000-b7f76000 r-xp 00000000 03:03 8828       /lib/ld-2.3.6.so
b7f76000-b7f78000 rw-p 00013000 03:03 8828       /lib/ld-2.3.6.so
bfd61000-bfd76000 rw-p bfd61000 00:00 0          [stack]
ffffe000-fffff000 ---p 00000000 00:00 0          [vdso]

A lot more information can be obtained from the /proc file system. Some important files and their contents are:

/proc/devices

Available devices

/proc/modules

Kernel modules loaded

/proc/cmdline

Kernel command line

/proc/meminfo

Detailed information about memory usage

/proc/config.gz

gzip-compressed configuration file of the kernel currently running

/proc/PID/

Find information about processes currently running in the /proc/NNN directories, where NNN is the process ID (PID) of the relevant process. Every process can find its own characteristics in /proc/self/.

Further information is available in the text file /usr/src/linux/Documentation/filesystems/proc.txt (this file is available when the package kernel-source is installed).

2.6.1 procinfo

Important information from the /proc file system is summarized by the command procinfo:

tux > procinfo
Linux 3.11.10-17-desktop (geeko@buildhost) (gcc 4.8.1 20130909) #1 4CPU [jupiter.example.com]

Memory:      Total        Used        Free      Shared     Buffers      Cached
Mem:       8181908     8000632      181276           0       85472     2850872
Swap:     10481660        1576    10480084

Bootup: Mon Jul 28 09:54:13 2014    Load average: 1.61 0.85 0.74 2/904 25949

user  :       1:54:41.84  12.7%  page in :    2107312  disk 1:    52212r   20199w
nice  :       0:00:00.46   0.0%  page out:    1714461  disk 2:    19387r   10928w
system:       0:25:38.00   2.8%  page act:     466673  disk 3:      548r      10w
IOwait:       0:04:16.45   0.4%  page dea:     272297
hw irq:       0:00:00.42   0.0%  page flt:  105754526
sw irq:       0:01:26.48   0.1%  swap in :          0
idle  :      12:14:43.65  81.5%  swap out:        394
guest :       0:02:18.59   0.2%
uptime:       3:45:22.24         context :   99809844

irq  0:       121 timer                 irq 41:   3238224 hpet3
irq  8:         1 rtc0                  irq 42:   3251898 hpet4
irq  9:         0 acpi                  irq 43:   3156368 hpet5
irq 16:     14589 ehci_hcd:usb1         irq 45:         0 aerdrv, PCIe PME
irq 18:         0 i801_smbus            irq 46:         0 PCIe PME, pciehp
irq 19:    124861 ata_piix, ata_piix, f irq 47:         0 PCIe PME, pciehp
irq 22:   3742817 enp5s1                irq 48:         0 PCIe PME, pciehp
irq 23:    479248 ehci_hcd:usb2         irq 49:       387 snd_hda_intel
irq 40:   3216894 hpet2                 irq 50:   1088673 nvidia

To see all the information, use the parameter -a. The parameter -nN produces updates of the information every N seconds. In this case, terminate the program by pressing Q.

By default, the cumulative values are displayed. The parameter -d produces the differential values. procinfo -dn5 displays the values that have changed in the last five seconds:

2.6.2 System Control Parameters: /proc/sys/

System control parameters are used to modify the Linux kernel parameters at runtime. They reside in /proc/sys/ and can be viewed and modified with the sysctl command. To list all parameters, run sysctl -a. A single parameter can be listed with sysctl PARAMETER_NAME.

Parameters are grouped into categories and can be listed with sysctl CATEGORY or by listing the contents of the respective directories. The most important categories are listed below. The links to further readings require the installation of the package kernel-source.

sysctl dev (/proc/sys/dev/)

Device-specific information.

sysctl fs (/proc/sys/fs/)

Used file handles, quotas, and other file system-oriented parameters. For details see /usr/src/linux/Documentation/sysctl/fs.txt.

sysctl kernel (/proc/sys/kernel/)

Information about the task scheduler, system shared memory, and other kernel-related parameters. For details see /usr/src/linux/Documentation/sysctl/kernel.txt

systctl net (/proc/sys/net/)

Information about network bridges, and general network parameters (mainly the ipv4/ subdirectory). For details see /usr/src/linux/Documentation/sysctl/net.txt

sysctl vm (/proc/sys/vm/)

Entries in this path relate to information about the virtual memory, swapping, and caching. For details see /usr/src/linux/Documentation/sysctl/vm.txt

To set or change a parameter for the current session, use the command sysctl -w PARAMETER=VALUE. To permanently change a setting, add a line PARAMETER=VALUE to /etc/sysctl.conf.

2.7 Hardware Information

2.7.1 PCI Resources: lspci

Note
Note: Accessing PCI configuration.

Most operating systems require root user privileges to grant access to the computer's PCI configuration.

The command lspci lists the PCI resources:

root # lspci
00:00.0 Host bridge: Intel Corporation 82845G/GL[Brookdale-G]/GE/PE \
    DRAM Controller/Host-Hub Interface (rev 01)
00:01.0 PCI bridge: Intel Corporation 82845G/GL[Brookdale-G]/GE/PE \
    Host-to-AGP Bridge (rev 01)
00:1d.0 USB Controller: Intel Corporation 82801DB/DBL/DBM \
    (ICH4/ICH4-L/ICH4-M) USB UHCI Controller #1 (rev 01)
00:1d.1 USB Controller: Intel Corporation 82801DB/DBL/DBM \
    (ICH4/ICH4-L/ICH4-M) USB UHCI Controller #2 (rev 01)
00:1d.2 USB Controller: Intel Corporation 82801DB/DBL/DBM \
    (ICH4/ICH4-L/ICH4-M) USB UHCI Controller #3 (rev 01)
00:1d.7 USB Controller: Intel Corporation 82801DB/DBM \
    (ICH4/ICH4-M) USB2 EHCI Controller (rev 01)
00:1e.0 PCI bridge: Intel Corporation 82801 PCI Bridge (rev 81)
00:1f.0 ISA bridge: Intel Corporation 82801DB/DBL (ICH4/ICH4-L) \
    LPC Interface Bridge (rev 01)
00:1f.1 IDE interface: Intel Corporation 82801DB (ICH4) IDE \
    Controller (rev 01)
00:1f.3 SMBus: Intel Corporation 82801DB/DBL/DBM (ICH4/ICH4-L/ICH4-M) \
    SMBus Controller (rev 01)
00:1f.5 Multimedia audio controller: Intel Corporation 82801DB/DBL/DBM \
    (ICH4/ICH4-L/ICH4-M) AC'97 Audio Controller (rev 01)
01:00.0 VGA compatible controller: Matrox Graphics, Inc. G400/G450 (rev 85)
02:08.0 Ethernet controller: Intel Corporation 82801DB PRO/100 VE (LOM) \
    Ethernet Controller (rev 81)

Using -v results in a more detailed listing:

root # lspci -v
[...]
00:03.0 Ethernet controller: Intel Corporation 82540EM Gigabit Ethernet \
Controller (rev 02)
  Subsystem: Intel Corporation PRO/1000 MT Desktop Adapter
  Flags: bus master, 66MHz, medium devsel, latency 64, IRQ 19
  Memory at f0000000 (32-bit, non-prefetchable) [size=128K]
  I/O ports at d010 [size=8]
  Capabilities: [dc] Power Management version 2
  Capabilities: [e4] PCI-X non-bridge device
  Kernel driver in use: e1000
  Kernel modules: e1000

Information about device name resolution is obtained from the file /usr/share/pci.ids. PCI IDs not listed in this file are marked Unknown device.

The parameter -vv produces all the information that could be queried by the program. To view the pure numeric values, use the parameter -n.

2.7.2 USB Devices: lsusb

The command lsusb lists all USB devices. With the option -v, print a more detailed list. The detailed information is read from the directory /proc/bus/usb/. The following is the output of lsusb with these USB devices attached: hub, memory stick, hard disk and mouse.

root # lsusb
Bus 004 Device 007: ID 0ea0:2168 Ours Technology, Inc. Transcend JetFlash \
    2.0 / Astone USB Drive
Bus 004 Device 006: ID 04b4:6830 Cypress Semiconductor Corp. USB-2.0 IDE \
    Adapter
Bus 004 Device 005: ID 05e3:0605 Genesys Logic, Inc.
Bus 004 Device 001: ID 0000:0000
Bus 003 Device 001: ID 0000:0000
Bus 002 Device 001: ID 0000:0000
Bus 001 Device 005: ID 046d:c012 Logitech, Inc. Optical Mouse
Bus 001 Device 001: ID 0000:0000

2.7.3 Monitoring and Tuning the Thermal Subsystem: tmon

tmon is a tool to help visualize, tune, and test the complex thermal subsystem. When started without parameters, tmon runs in monitoring mode:

┌──────THERMAL ZONES(SENSORS)──────────────────────────────┐
│Thermal Zones:                 acpitz00                   │
│Trip Points:                   PC                         │
└──────────────────────────────────────────────────────────┘
┌─────────── COOLING DEVICES ──────────────────────────────┐
│ID  Cooling Dev   Cur    Max   Thermal Zone Binding       │
│00    Processor     0      3   ││││││││││││               │
│01    Processor     0      3   ││││││││││││               │
│02    Processor     0      3   ││││││││││││               │
│03    Processor     0      3   ││││││││││││               │
│04 intel_powerc    -1     50   ││││││││││││               │
└──────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────┐
│                         10        20        30        40 │
│acpitz 0:[  8][>>>>>>>>>P9                    C31         │
└──────────────────────────────────────────────────────────┘
┌────────────────── CONTROLS ──────────────────────────────┐
│PID gain: kp=0.36 ki=5.00 kd=0.19 Output 0.00             │
│Target Temp: 65.0C, Zone: 0, Control Device: None         │
└──────────────────────────────────────────────────────────┘

 Ctrl-c - Quit   TAB - Tuning

For detailed information on how to interpret the data, how to log thermal data and how to use tmon to test and tune cooling devices and sensors, refer to the man page: man 8 tmon. The package tmon is not installed by default.

2.7.4 MCELog: Machine Check Exceptions (MCE)

The mcelog package logs and parses/translates Machine Check Exceptions (MCE) on hardware errors (also including memory errors). Formerly this has been done by a cron job executed hourly. Now hardware errors are immediately processed by an mcelog daemon.

However, the mcelog service is not enabled by default, resulting in memory and CPU errors also not being logged by default. In addition, mcelog has a new feature to also handle predictive bad page offlining and automatic core offlining when cache errors happen.

The service can either be enabled and started via the YaST system services editor or via command line:

root # systemctl enable mcelog
root # systemctl start mcelog

2.7.5 x86_64: dmidecode: DMI Table Decoder

dmidecode shows the machine's DMI table containing information such as serial numbers and BIOS revisions of the hardware.

root # dmidecode
# dmidecode 2.12
SMBIOS 2.5 present.
27 structures occupying 1298 bytes.
Table at 0x000EB250.

Handle 0x0000, DMI type 4, 35 bytes
Processor Information
        Socket Designation: J1PR
        Type: Central Processor
        Family: Other
        Manufacturer: Intel(R) Corporation
        ID: E5 06 01 00 FF FB EB BF
        Version: Intel(R) Core(TM) i5 CPU         750  @ 2.67GHz
        Voltage: 1.1 V
        External Clock: 133 MHz
        Max Speed: 4000 MHz
        Current Speed: 2667 MHz
        Status: Populated, Enabled
        Upgrade: Other
        L1 Cache Handle: 0x0004
        L2 Cache Handle: 0x0003
        L3 Cache Handle: 0x0001
        Serial Number: Not Specified
        Asset Tag: Not Specified
        Part Number: Not Specified
[..]

2.8 Files and File Systems

For file system-specific information, refer to Storage Administration Guide.

2.8.1 Determine the File Type: file

The command file determines the type of a file or a list of files by checking /usr/share/misc/magic.

tux > file /usr/bin/file
/usr/bin/file: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), \
    for GNU/Linux 2.6.4, dynamically linked (uses shared libs), stripped

The parameter -f LIST specifies a file with a list of file names to examine. The -z allows file to look inside compressed files:

tux > file /usr/share/man/man1/file.1.gz
/usr/share/man/man1/file.1.gz: gzip compressed data, from Unix, max compression
tux > file -z /usr/share/man/man1/file.1.gz
/usr/share/man/man1/file.1.gz: troff or preprocessor input text \
    (gzip compressed data, from Unix, max compression)

The parameter -i outputs a mime type string rather than the traditional description.

tux > file -i /usr/share/misc/magic
/usr/share/misc/magic: text/plain charset=utf-8

2.8.2 File Systems and Their Usage: mount, df and du

The command mount shows which file system (device and type) is mounted at which mount point:

root # mount
/dev/sda2 on / type ext4 (rw,acl,user_xattr)
proc on /proc type proc (rw)
sysfs on /sys type sysfs (rw)
debugfs on /sys/kernel/debug type debugfs (rw)
devtmpfs on /dev type devtmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,mode=1777)
devpts on /dev/pts type devpts (rw,mode=0620,gid=5)
/dev/sda3 on /home type ext3 (rw)
securityfs on /sys/kernel/security type securityfs (rw)
fusectl on /sys/fs/fuse/connections type fusectl (rw)
gvfs-fuse-daemon on /home/tux/.gvfs type fuse.gvfs-fuse-daemon \
(rw,nosuid,nodev,user=tux)

Obtain information about total usage of the file systems with the command df. The parameter -h (or --human-readable) transforms the output into a form understandable for common users.

tux > df -h
Filesystem            Size  Used Avail Use% Mounted on
/dev/sda2              20G  5,9G   13G  32% /
devtmpfs              1,6G  236K  1,6G   1% /dev
tmpfs                 1,6G  668K  1,6G   1% /dev/shm
/dev/sda3             208G   40G  159G  20% /home

Display the total size of all the files in a given directory and its subdirectories with the command du. The parameter -s suppresses the output of detailed information and gives only a total for each argument. -h again transforms the output into a human-readable form:

tux > du -sh /opt
192M    /opt

2.8.3 Additional Information about ELF Binaries

Read the content of binaries with the readelf utility. This even works with ELF files that were built for other hardware architectures:

tux > readelf --file-header /bin/ls
ELF Header:
  Magic:   7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00
  Class:                             ELF64
  Data:                              2's complement, little endian
  Version:                           1 (current)
  OS/ABI:                            UNIX - System V
  ABI Version:                       0
  Type:                              EXEC (Executable file)
  Machine:                           Advanced Micro Devices X86-64
  Version:                           0x1
  Entry point address:               0x402540
  Start of program headers:          64 (bytes into file)
  Start of section headers:          95720 (bytes into file)
  Flags:                             0x0
  Size of this header:               64 (bytes)
  Size of program headers:           56 (bytes)
  Number of program headers:         9
  Size of section headers:           64 (bytes)
  Number of section headers:         32
  Section header string table index: 31

2.8.4 File Properties: stat

The command stat displays file properties:

tux > stat /etc/profile
  File: `/etc/profile'
  Size: 9662            Blocks: 24         IO Block: 4096   regular file
Device: 802h/2050d      Inode: 132349      Links: 1
Access: (0644/-rw-r--r--)  Uid: (    0/    root)   Gid: (    0/    root)
Access: 2009-03-20 07:51:17.000000000 +0100
Modify: 2009-01-08 19:21:14.000000000 +0100
Change: 2009-03-18 12:55:31.000000000 +0100

The parameter --file-system produces details of the properties of the file system in which the specified file is located:

tux > stat /etc/profile --file-system
  File: "/etc/profile"
    ID: d4fb76e70b4d1746 Namelen: 255     Type: ext2/ext3
Block size: 4096       Fundamental block size: 4096
Blocks: Total: 2581445    Free: 1717327    Available: 1586197
Inodes: Total: 655776     Free: 490312

2.9 User Information

2.9.1 User Accessing Files: fuser

It can be useful to determine what processes or users are currently accessing certain files. Suppose, for example, you want to unmount a file system mounted at /mnt. umount returns "device is busy." The command fuser can then be used to determine what processes are accessing the device:

tux > fuser -v /mnt/*

                     USER        PID ACCESS COMMAND
/mnt/notes.txt       tux    26597 f....  less

Following termination of the less process, which was running on another terminal, the file system can successfully be unmounted. When used with -k option, fuser will terminate processes accessing the file as well.

2.9.2 Who Is Doing What: w

With the command w, find out who is logged in to the system and what each user is doing. For example:

tux > w
 16:00:59 up 1 day,  2:41,  3 users,  load average: 0.00, 0.01, 0.05
USER     TTY      FROM             LOGIN@   IDLE   JCPU   PCPU WHAT
tux      :0       console          Wed13   ?xdm?   8:15   0.03s /usr/lib/gdm/gd
tux      console  :0               Wed13   26:41m  0.00s  0.03s /usr/lib/gdm/gd
tux      pts/0    :0               Wed13   20:11   0.10s  2.89s /usr/lib/gnome-

If any users of other systems have logged in remotely, the parameter -f shows the computers from which they have established the connection.

2.10 Time and Date

2.10.1 Time Measurement with time

Determine the time spent by commands with the time utility. This utility is available in two versions: as a Bash built-in and as a program (/usr/bin/time).

tux >  time find . > /dev/null

real    0m4.051s1
user    0m0.042s2
sys     0m0.205s3

1

The real time that elapsed from the command's start-up until it finished.

2

CPU time of the user as reported by the times system call.

3

CPU time of the system as reported by the times system call.

The output of /usr/bin/time is much more detailed. It is recommended to run it with the -v switch to produce human-readable output.

/usr/bin/time -v find . > /dev/null
        Command being timed: "find ."
        User time (seconds): 0.24
        System time (seconds): 2.08
        Percent of CPU this job got: 25%
        Elapsed (wall clock) time (h:mm:ss or m:ss): 0:09.03
        Average shared text size (kbytes): 0
        Average unshared data size (kbytes): 0
        Average stack size (kbytes): 0
        Average total size (kbytes): 0
        Maximum resident set size (kbytes): 2516
        Average resident set size (kbytes): 0
        Major (requiring I/O) page faults: 0
        Minor (reclaiming a frame) page faults: 1564
        Voluntary context switches: 36660
        Involuntary context switches: 496
        Swaps: 0
        File system inputs: 0
        File system outputs: 0
        Socket messages sent: 0
        Socket messages received: 0
        Signals delivered: 0
        Page size (bytes): 4096
        Exit status: 0

2.11 Graph Your Data: RRDtool

There are a lot of data in the world around you, which can be easily measured in time. For example, changes in the temperature, or the number of data sent or received by your computer's network interface. RRDtool can help you store and visualize such data in detailed and customizable graphs.

RRDtool is available for most Unix platforms and Linux distributions. SUSE® Linux Enterprise Server ships RRDtool as well. Install it either with YaST or by entering

zypper install rrdtool in the command line as root.

Tip
Tip: Bindings

There are Perl, Python, Ruby, and PHP bindings available for RRDtool, so that you can write your own monitoring scripts in your preferred scripting language.

2.11.1 How RRDtool Works

RRDtool is an abbreviation of Round Robin Database tool. Round Robin is a method for manipulating with a constant amount of data. It uses the principle of a circular buffer, where there is no end nor beginning to the data row which is being read. RRDtool uses Round Robin Databases to store and read its data.

As mentioned above, RRDtool is designed to work with data that change in time. The ideal case is a sensor which repeatedly reads measured data (like temperature, speed etc.) in constant periods of time, and then exports them in a given format. Such data are perfectly ready for RRDtool, and it is easy to process them and create the desired output.

Sometimes it is not possible to obtain the data automatically and regularly. Their format needs to be pre-processed before it is supplied to RRDtool, and often you need to manipulate RRDtool even manually.

The following is a simple example of basic RRDtool usage. It illustrates all three important phases of the usual RRDtool workflow: creating a database, updating measured values, and viewing the output.

2.11.2 A Practical Example

Suppose we want to collect and view information about the memory usage in the Linux system as it changes in time. To make the example more vivid, we measure the currently free memory over a period of 40 seconds in 4-second intervals. Three applications that usually consume a lot of system memory are started and closed: the Firefox Web browser, the Evolution e-mail client, and the Eclipse development framework.

2.11.2.1 Collecting Data

RRDtool is very often used to measure and visualize network traffic. In such case, the Simple Network Management Protocol (SNMP) is used. This protocol can query network devices for relevant values of their internal counters. Exactly these values are to be stored with RRDtool. For more information on SNMP, see http://www.net-snmp.org/.

Our situation is different—we need to obtain the data manually. A helper script free_mem.sh repetitively reads the current state of free memory and writes it to the standard output.

tux > cat free_mem.sh
INTERVAL=4
for steps in {1..10}
do
    DATE=`date +%s`
    FREEMEM=`free -b | grep "Mem" | awk '{ print $4 }'`
    sleep $INTERVAL
    echo "rrdtool update free_mem.rrd $DATE:$FREEMEM"
done
  • The time interval is set to 4 seconds, and is implemented with the sleep command.

  • RRDtool accepts time information in a special format - so called Unix time. It is defined as the number of seconds since the midnight of January 1, 1970 (UTC). For example, 1272907114 represents 2010-05-03 17:18:34.

  • The free memory information is reported in bytes with free -b. Prefer to supply basic units (bytes) instead of multiple units (like kilobytes).

  • The line with the echo ... command contains the future name of the database file (free_mem.rrd), and together creates a command line for updating RRDtool values.

After running free_mem.sh, you see an output similar to this:

tux > sh free_mem.sh
rrdtool update free_mem.rrd 1272974835:1182994432
rrdtool update free_mem.rrd 1272974839:1162817536
rrdtool update free_mem.rrd 1272974843:1096269824
rrdtool update free_mem.rrd 1272974847:1034219520
rrdtool update free_mem.rrd 1272974851:909438976
rrdtool update free_mem.rrd 1272974855:832454656
rrdtool update free_mem.rrd 1272974859:829120512
rrdtool update free_mem.rrd 1272974863:1180377088
rrdtool update free_mem.rrd 1272974867:1179369472
rrdtool update free_mem.rrd 1272974871:1181806592

It is convenient to redirect the command's output to a file with

sh free_mem.sh > free_mem_updates.log

to simplify its future execution.

2.11.2.2 Creating the Database

Create the initial Robin Round database for our example with the following command:

tux >  rrdtool create free_mem.rrd --start 1272974834 --step=4 \
DS:memory:GAUGE:600:U:U RRA:AVERAGE:0.5:1:24
Points to Notice
  • This command creates a file called free_mem.rrd for storing our measured values in a Round Robin type database.

  • The --start option specifies the time (in Unix time) when the first value will be added to the database. In this example, it is one less than the first time value of the free_mem.sh output (1272974835).

  • The --step specifies the time interval in seconds with which the measured data will be supplied to the database.

  • The DS:memory:GAUGE:600:U:U part introduces a new data source for the database. It is called memory, its type is gauge, the maximum number between two updates is 600 seconds, and the minimal and maximal value in the measured range are unknown (U).

  • RRA:AVERAGE:0.5:1:24 creates Round Robin archive (RRA) whose stored data are processed with the consolidation functions (CF) that calculates the average of data points. 3 arguments of the consolidation function are appended to the end of the line.

If no error message is displayed, then free_mem.rrd database is created in the current directory:

tux > ls -l free_mem.rrd
-rw-r--r-- 1 tux users 776 May  5 12:50 free_mem.rrd

2.11.2.3 Updating Database Values

After the database is created, you need to fill it with the measured data. In Section 2.11.2.1, “Collecting Data”, we already prepared the file free_mem_updates.log which consists of rrdtool update commands. These commands do the update of database values for us.

tux > sh free_mem_updates.log; ls -l free_mem.rrd
-rw-r--r--  1 tux users  776 May  5 13:29 free_mem.rrd

As you can see, the size of free_mem.rrd remained the same even after updating its data.

2.11.2.4 Viewing Measured Values

We have already measured the values, created the database, and stored the measured value in it. Now we can play with the database, and retrieve or view its values.

To retrieve all the values from our database, enter the following on the command line:

tux > rrdtool fetch free_mem.rrd AVERAGE --start 1272974830 \
--end 1272974871
          memory
1272974832: nan
1272974836: 1.1729059840e+09
1272974840: 1.1461806080e+09
1272974844: 1.0807572480e+09
1272974848: 1.0030243840e+09
1272974852: 8.9019289600e+08
1272974856: 8.3162112000e+08
1272974860: 9.1693465600e+08
1272974864: 1.1801251840e+09
1272974868: 1.1799787520e+09
1272974872: nan
Points to Notice
  • AVERAGE will fetch average value points from the database, because only one data source is defined (Section 2.11.2.2, “Creating the Database”) with AVERAGE processing and no other function is available.

  • The first line of the output prints the name of the data source as defined in Section 2.11.2.2, “Creating the Database”.

  • The left results column represents individual points in time, while the right one represents corresponding measured average values in scientific notation.

  • The nan in the last line stands for not a number.

Now a graph representing the values stored in the database is drawn:

tux > rrdtool graph free_mem.png \
--start 1272974830 \
--end 1272974871 \
--step=4 \
DEF:free_memory=free_mem.rrd:memory:AVERAGE \
LINE2:free_memory#FF0000 \
--vertical-label "GB" \
--title "Free System Memory in Time" \
--zoom 1.5 \
--x-grid SECOND:1:SECOND:4:SECOND:10:0:%X
Points to Notice
  • free_mem.png is the file name of the graph to be created.

  • --start and --end limit the time range within which the graph will be drawn.

  • --step specifies the time resolution (in seconds) of the graph.

  • The DEF:... part is a data definition called free_memory. Its data are read from the free_mem.rrd database and its data source called memory. The average value points are calculated, because no others were defined in Section 2.11.2.2, “Creating the Database”.

  • The LINE... part specifies properties of the line to be drawn into the graph. It is 2 pixels wide, its data come from the free_memory definition, and its color is red.

  • --vertical-label sets the label to be printed along the y axis, and --title sets the main label for the whole graph.

  • --zoom specifies the zoom factor for the graph. This value must be greater than zero.

  • --x-grid specifies how to draw grid lines and their labels into the graph. Our example places them every second, while major grid lines are placed every 4 seconds. Labels are placed every 10 seconds under the major grid lines.

Example Graph Created with RRDtool
Figure 2.1: Example Graph Created with RRDtool

2.11.3 For More Information

RRDtool is a very complex tool with a lot of sub-commands and command line options. Some are easy to understand, but to make it produce the results you want and fine-tune them according to your liking may require a lot of effort.

Apart from RRDtool's man page (man 1 rrdtool) which gives you only basic information, you should have a look at the RRDtool home page. There is a detailed documentation of the rrdtool command and all its sub-commands. There are also several tutorials to help you understand the common RRDtool workflow.

If you are interested in monitoring network traffic, have a look at MRTG (Multi Router Traffic Grapher). MRTG can graph the activity of many network devices. It can use RRDtool.

3 Analyzing and Managing System Log Files

  • Filename: tuning_logfiles.xml
  • ID: cha.tuning.logfiles

System log file analysis is one of the most important tasks when analyzing the system. In fact, looking at the system log files should be the first thing to do when maintaining or troubleshooting a system. SUSE Linux Enterprise Server automatically logs almost everything that happens on the system in detail. Since the move to systemd, kernel messages and messages of system services registered with systemd are logged in systemd journal (see Chapter 15, journalctl: Query the systemd Journal). Other log files (mainly those of system applications) are written in plain text and can be easily read using an editor or pager. It is also possible to parse them using scripts. This allows you to filter their content.

3.1 System Log Files in /var/log/

System log files are always located under the /var/log directory. The following list presents an overview of all system log files from SUSE Linux Enterprise Server present after a default installation. Depending on your installation scope, /var/log also contains log files from other services and applications not listed here. Some files and directories described below are placeholders and are only used, when the corresponding application is installed. Most log files are only visible for the user root.

apparmor/

AppArmor log files. See Part IV, “Confining Privileges with AppArmor for details of AppArmor.

audit/

Logs from the audit framework. See Part VI, “The Linux Audit Framework for details.

ConsoleKit/

Logs of the ConsoleKit daemon (daemon for tracking what users are logged in and how they interact with the computer).

cups/

Access and error logs of the Common Unix Printing System (cups).

firewall

Firewall logs.

gdm/

Log files from the GNOME display manager.

krb5/

Log files from the Kerberos network authentication system.

lastlog

A database containing information on the last login of each user. Use the command lastlog to view. See man 8 lastlog for more information.

localmessages

Log messages of some boot scripts, for example the log of the DHCP client.

mail*

Mail server (postfix, sendmail) logs.

messages

This is the default place where all kernel and system log messages go and should be the first place (along with /var/log/warn) to look at in case of problems.

NetworkManager

NetworkManager log files.

news/

Log messages from a news server.

ntp

Logs from the Network Time Protocol daemon (ntpd).

pk_backend_zypp*

PackageKit (with libzypp back-end) log files.

puppet/

Log files from the data center automation tool puppet.

samba/

Log files from Samba, the Windows SMB/CIFS file server.

warn

Log of all system warnings and errors. This should be the first place (along with the output of the systemd journal) to look in case of problems.

wtmp

Database of all login/logout activities, and remote connections. Use the command last to view. See man 1 last for more information.

xinetd.log

Log files from the extended Internet services daemon (xinetd).

Xorg.0.log

X.Org start-up log file. Refer to this in case you have problems starting X.Org. Copies from previous X.Org starts are numbered Xorg.?.log.

YaST2/

All YaST log files.

zypp/

libzypp log files. Refer to these files for the package installation history.

zypper.log

Logs from the command line installer zypper.

3.2 Viewing and Parsing Log Files

To view log files, you can use any text editor. There is also a simple YaST module for viewing the system log available in the YaST control center under Miscellaneous › System Log.

For viewing log files in a text console, use the commands less or more. Use head and tail to view the beginning or end of a log file. To view entries appended to a log file in real-time use tail -f. For information about how to use these tools, see their man pages.

To search for strings or regular expressions in log files use grep. awk is useful for parsing and rewriting log files.

3.3 Managing Log Files with logrotate

Log files under /var/log grow on a daily basis and quickly become very large. logrotate is a tool that helps you manage log files and their growth. It allows automatic rotation, removal, compression, and mailing of log files. Log files can be handled periodically (daily, weekly, or monthly) or when exceeding a particular size.

logrotate is usually run daily by systemd, and thus usually modifies log files only once a day. However, exceptions occur when a log file is modified because of its size, if logrotate is run multiple times a day, or if --force is enabled. Use /var/lib/misc/logrotate.status to find out when a particular file was last rotated.

The main configuration file of logrotate is /etc/logrotate.conf. System packages and programs that produce log files (for example, apache2) put their own configuration files in the /etc/logrotate.d/ directory. The content of /etc/logrotate.d/ is included via /etc/logrotate.conf.

Example 3.1: Example for /etc/logrotate.conf
# see "man logrotate" for details
# rotate log files weekly
weekly

# keep 4 weeks worth of backlogs
rotate 4

# create new (empty) log files after rotating old ones
create

# use date as a suffix of the rotated file
dateext

# uncomment this if you want your log files compressed
#compress

# comment these to switch compression to use gzip or another
# compression scheme
compresscmd /usr/bin/bzip2
uncompresscmd /usr/bin/bunzip2

# RPM packages drop log rotation information into this directory
include /etc/logrotate.d
Important
Important: Avoid Permission Conflicts

The create option pays heed to the modes and ownerships of files specified in /etc/permissions*. If you modify these settings, make sure no conflicts arise.

3.4 Monitoring Log Files with logwatch

logwatch is a customizable, pluggable log-monitoring script. It parses system logs, extracts the important information and presents them in a human readable manner. To use logwatch, install the logwatch package.

logwatch can either be used at the command line to generate on-the-fly reports, or via cron to regularly create custom reports. Reports can either be printed on the screen, saved to a file, or be mailed to a specified address. The latter is especially useful when automatically generating reports via cron.

On the command line, you can tell logwatch for which service and time span to generate a report and how much detail should be included:

# Detailed report on all kernel messages from yesterday
logwatch --service kernel --detail High --range Yesterday --print

# Low detail report on all sshd events recorded (incl. archived logs)
logwatch --service sshd --detail Low --range All --archives --print

# Mail a report on all smartd messages from May 5th to May 7th to root@localhost
logwatch --service smartd --range 'between 5/5/2005 and 5/7/2005' \
--mailto root@localhost --print

The --range option has got a complex syntax—see logwatch --range help for details. A list of all services that can be queried is available with the following command:

ls /usr/share/logwatch/default.conf/services/ | sed 's/\.conf//g'

logwatch can be customized to great detail. However, the default configuration should usually be sufficient. The default configuration files are located under /usr/share/logwatch/default.conf/. Never change them because they would get overwritten again with the next update. Rather place custom configuration in /etc/logwatch/conf/ (you may use the default configuration file as a template, though). A detailed HOWTO on customizing logwatch is available at /usr/share/doc/packages/logwatch/HOWTO-Customize-LogWatch. The following configuration files exist:

logwatch.conf

The main configuration file. The default version is extensively commented. Each configuration option can be overwritten on the command line.

ignore.conf

Filter for all lines that should globally be ignored by logwatch.

services/*.conf

The service directory holds configuration files for each service you can generate a report for.

logfiles/*.conf

Specifications on which log files should be parsed for each service.

3.5 Using logger to Make System Log Entries

logger is a tool for making entries in the system log. It provides a shell command interface to the rsyslogd system log module. For example, the following line outputs its message in /var/log/messages or directly in the journal (if no logging facility is running):

logger -t Test "This message comes from $USER"

Depending on the current user and host name, the log contains a line similar to this:

Sep 28 13:09:31 venus Test: This message comes from tux

Part III Kernel Monitoring

4 SystemTap—Filtering and Analyzing System Data

SystemTap provides a command line interface and a scripting language to examine the activities of a running Linux system, particularly the kernel, in fine detail. SystemTap scripts are written in the SystemTap scripting language, are then compiled to C-code kernel modules and inserted into the kerne…

5 Kernel Probes

Kernel probes are a set of tools to collect Linux kernel debugging and performance information. Developers and system administrators usually use them either to debug the kernel, or to find system performance bottlenecks. The reported data can then be used to tune the system for better performance.

6 Hardware-Based Performance Monitoring with Perf

Perf is an interface to access the performance monitoring unit (PMU) of a processor and to record and display software events such as page faults. It supports system-wide, per-thread, and KVM virtualization guest monitoring.

7 OProfile—System-Wide Profiler

OProfile is a profiler for dynamic program analysis. It investigates the behavior of a running program and gathers information. This information can be viewed and gives hints for further optimization.

It is not necessary to recompile or use wrapper libraries to use OProfile. Not even a kernel patch is needed. Usually, when profiling an application, a small overhead is expected, depending on the workload and sampling frequency.

4 SystemTap—Filtering and Analyzing System Data

  • Filename: tuning_systemtap.xml
  • ID: cha.tuning.systemtap

SystemTap provides a command line interface and a scripting language to examine the activities of a running Linux system, particularly the kernel, in fine detail. SystemTap scripts are written in the SystemTap scripting language, are then compiled to C-code kernel modules and inserted into the kernel. The scripts can be designed to extract, filter and summarize data, thus allowing the diagnosis of complex performance problems or functional problems. SystemTap provides information similar to the output of tools like netstat, ps, top, and iostat. However, more filtering and analysis options can be used for the collected information.

4.1 Conceptual Overview

Each time you run a SystemTap script, a SystemTap session is started. Several passes are done on the script before it is allowed to run. Then, the script is compiled into a kernel module and loaded. If the script has been executed before and no system components have changed (for example, different compiler or kernel versions, library paths, or script contents), SystemTap does not compile the script again. Instead, it uses the *.c and *.ko data stored in the SystemTap cache (~/.systemtap).

The module is unloaded when the tap has finished running. For an example, see the test run in Section 4.2, “Installation and Setup” and the respective explanation.

4.1.1 SystemTap Scripts

SystemTap usage is based on SystemTap scripts (*.stp). They tell SystemTap which type of information to collect, and what to do once that information is collected. The scripts are written in the SystemTap scripting language that is similar to AWK and C. For the language definition, see http://sourceware.org/systemtap/langref/. A lot of useful example scripts are available from http://www.sourceware.org/systemtap/examples/.

The essential idea behind a SystemTap script is to name events, and to give them handlers. When SystemTap runs the script, it monitors for certain events. When an event occurs, the Linux kernel runs the handler as a sub-routine, then resumes. Thus, events serve as the triggers for handlers to run. Handlers can record specified data and print it in a certain manner.

The SystemTap language only uses a few data types (integers, strings, and associative arrays of these), and full control structures (blocks, conditionals, loops, functions). It has a lightweight punctuation (semicolons are optional) and does not need detailed declarations (types are inferred and checked automatically).

For more information about SystemTap scripts and their syntax, refer to Section 4.3, “Script Syntax” and to the stapprobes and stapfuncs man pages, that are available with the systemtap-docs package.

4.1.2 Tapsets

Tapsets are a library of pre-written probes and functions that can be used in SystemTap scripts. When a user runs a SystemTap script, SystemTap checks the script's probe events and handlers against the tapset library. SystemTap then loads the corresponding probes and functions before translating the script to C. Like SystemTap scripts themselves, tapsets use the file name extension *.stp.

However, unlike SystemTap scripts, tapsets are not meant for direct execution. They constitute the library from which other scripts can pull definitions. Thus, the tapset library is an abstraction layer designed to make it easier for users to define events and functions. Tapsets provide aliases for functions that users could want to specify as an event. Knowing the proper alias is often easier than remembering specific kernel functions that might vary between kernel versions.

4.1.3 Commands and Privileges

The main commands associated with SystemTap are stap and staprun. To execute them, you either need root privileges or must be a member of the stapdev or stapusr group.

stap

SystemTap front-end. Runs a SystemTap script (either from file, or from standard input). It translates the script into C code, compiles it, and loads the resulting kernel module into a running Linux kernel. Then, the requested system trace or probe functions are performed.

staprun

SystemTap back-end. Loads and unloads kernel modules produced by the SystemTap front-end.

For a list of options for each command, use --help. For details, refer to the stap and the staprun man pages.

To avoid giving root access to users solely to enable them to work with SystemTap, use one of the following SystemTap groups. They are not available by default on SUSE Linux Enterprise Server, but you can create the groups and modify the access rights accordingly. Also adjust the permissions of the staprun command if the security implications are appropriate for your environment.

stapdev

Members of this group can run SystemTap scripts with stap, or run SystemTap instrumentation modules with staprun. As running stap involves compiling scripts into kernel modules and loading them into the kernel, members of this group still have effective root access.

stapusr

Members of this group are only allowed to run SystemTap instrumentation modules with staprun. In addition, they can only run those modules from /lib/modules/KERNEL_VERSION/systemtap/. This directory must be owned by root and must only be writable for the root user.

4.1.4 Important Files and Directories

The following list gives an overview of the SystemTap main files and directories.

/lib/modules/KERNEL_VERSION/systemtap/

Holds the SystemTap instrumentation modules.

/usr/share/systemtap/tapset/

Holds the standard library of tapsets.

/usr/share/doc/packages/systemtap/examples

Holds several example SystemTap scripts for various purposes. Only available if the systemtap-docs package is installed.

~/.systemtap/cache

Data directory for cached SystemTap files.

/tmp/stap*

Temporary directory for SystemTap files, including translated C code and kernel object.

4.2 Installation and Setup

As SystemTap needs information about the kernel, some additional kernel-related packages must be installed. For each kernel you want to probe with SystemTap, you need to install a set of the following packages. This set should exactly match the kernel version and flavor (indicated by * in the overview below).

Important
Important: Repository for Packages with Debugging Information

If you subscribed your system for online updates, you can find debuginfo packages in the *-Debuginfo-Updates online installation repository relevant for SUSE Linux Enterprise Server 12 SP3. Use YaST to enable the repository.

For the classic SystemTap setup, install the following packages (using either YaST or zypper).

  • systemtap

  • systemtap-server

  • systemtap-docs (optional)

  • kernel-*-base

  • kernel-*-debuginfo

  • kernel-*-devel

  • kernel-source-*

  • gcc

To get access to the man pages and to a helpful collection of example SystemTap scripts for various purposes, additionally install the systemtap-docs package.

To check if all packages are correctly installed on the machine and if SystemTap is ready to use, execute the following command as root.

stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}'

It probes the currently used kernel by running a script and returning an output. If the output is similar to the following, SystemTap is successfully deployed and ready to use:

Pass 1: parsed user script and 59 library script(s) in 80usr/0sys/214real ms.
Pass 2: analyzed script: 1 probe(s), 11 function(s), 2 embed(s), 1 global(s) in
 140usr/20sys/412real ms.
Pass 3: translated to C into
 "/tmp/stapDwEk76/stap_1856e21ea1c246da85ad8c66b4338349_4970.c" in 160usr/0sys/408real ms.
Pass 4: compiled C into "stap_1856e21ea1c246da85ad8c66b4338349_4970.ko" in
 2030usr/360sys/10182real ms.
Pass 5: starting run.
 read performed
Pass 5: run completed in 10usr/20sys/257real ms.

1

Checks the script against the existing tapset library in /usr/share/systemtap/tapset/ for any tapsets used. Tapsets are scripts that form a library of pre-written probes and functions that can be used in SystemTap scripts.

2

Examines the script for its components.

3

Translates the script to C. Runs the system C compiler to create a kernel module from it. Both the resulting C code (*.c) and the kernel module (*.ko) are stored in the SystemTap cache, ~/.systemtap.

4

Loads the module and enables all the probes (events and handlers) in the script by hooking into the kernel. The event being probed is a Virtual File System (VFS) read. As the event occurs on any processor, a valid handler is executed (prints the text read performed) and closed with no errors.

5

After the SystemTap session is terminated, the probes are disabled, and the kernel module is unloaded.

In case any error messages appear during the test, check the output for hints about any missing packages and make sure they are installed correctly. Rebooting and loading the appropriate kernel may also be needed.

4.3 Script Syntax

SystemTap scripts consist of the following two components:

SystemTap Events (Probe Points)

Name the kernel events at the associated handler should be executed. Examples for events are entering or exiting a certain function, a timer expiring, or starting or terminating a session.

SystemTap Handlers (Probe Body)

Series of script language statements that specify the work to be done whenever a certain event occurs. This normally includes extracting data from the event context, storing them into internal variables, or printing results.

An event and its corresponding handler is collectively called a probe. SystemTap events are also called probe points. A probe's handler is also called a probe body.

Comments can be inserted anywhere in the SystemTap script in various styles: using either #, /* */, or // as marker.

4.3.1 Probe Format

A SystemTap script can have multiple probes. They must be written in the following format:

probe EVENT {STATEMENTS}

Each probe has a corresponding statement block. This statement block must be enclosed in { } and contains the statements to be executed per event.

Example 4.1: Simple SystemTap Script

The following example shows a simple SystemTap script.

probe1 begin2
{3
   printf4 ("hello world\n")5
   exit ()6
}7

1

Start of the probe.

2

Event begin (the start of the SystemTap session).

3

Start of the handler definition, indicated by {.

4

First function defined in the handler: the printf function.

5

String to be printed by the printf function, followed by a line break (/n).

6

Second function defined in the handler: the exit() function. Note that the SystemTap script will continue to run until the exit() function executes. If you want to stop the execution of the script before, stop it manually by pressing CtrlC.

7

End of the handler definition, indicated by }.

The event begin 2 (the start of the SystemTap session) triggers the handler enclosed in { }. Here, that is the printf function 4. In this case, it prints hello world followed by a new line 5. Then, the script exits.

If your statement block holds several statements, SystemTap executes these statements in sequence—you do not need to insert special separators or terminators between multiple statements. A statement block can also be nested within another statement blocks. Generally, statement blocks in SystemTap scripts use the same syntax and semantics as in the C programming language.

4.3.2 SystemTap Events (Probe Points)

SystemTap supports several built-in events.

The general event syntax is a dotted-symbol sequence. This allows a breakdown of the event namespace into parts. Each component identifier may be parametrized by a string or number literal, with a syntax like a function call. A component may include a * character, to expand to other matching probe points. A probe point may be followed by a ? character, to indicate that it is optional, and that no error should result if it fails to expand. Alternately, a probe point may be followed by a ! character to indicate that it is both optional and sufficient.

SystemTap supports multiple events per probe—they need to be separated by a comma (,). If multiple events are specified in a single probe, SystemTap will execute the handler when any of the specified events occur.

In general, events can be classified into the following categories:

  • Synchronous events: Occur when any process executes an instruction at a particular location in kernel code. This gives other events a reference point (instruction address) from which more contextual data may be available.

    An example for a synchronous event is vfs.FILE_OPERATION: The entry to the FILE_OPERATION event for Virtual File System (VFS). For example, in Section 4.2, “Installation and Setup”, read is the FILE_OPERATION event used for VFS.

  • Asynchronous events: Not tied to a particular instruction or location in code. This family of probe points consists mainly of counters, timers, and similar constructs.

    Examples for asynchronous events are: begin (start of a SystemTap session—when a SystemTap script is run, end (end of a SystemTap session), or timer events. Timer events specify a handler to be executed periodically, like example timer.s(SECONDS), or timer.ms(MILLISECONDS).

    When used together with other probes that collect information, timer events allow you to print periodic updates and see how that information changes over time.

Example 4.2: Probe with Timer Event

For example, the following probe would print the text hello world every 4 seconds:

probe timer.s(4)
{
   printf("hello world\n")
}

For detailed information about supported events, refer to the stapprobes man page. The See Also section of the man page also contains links to other man pages that discuss supported events for specific subsystems and components.

4.3.3 SystemTap Handlers (Probe Body)

Each SystemTap event is accompanied by a corresponding handler defined for that event, consisting of a statement block.

4.3.3.1 Functions

If you need the same set of statements in multiple probes, you can place them in a function for easy reuse. Functions are defined by the keyword function followed by a name. They take any number of string or numeric arguments (by value) and may return a single string or number.

function FUNCTION_NAME(ARGUMENTS) {STATEMENTS}
probe EVENT {FUNCTION_NAME(ARGUMENTS)}

The statements in FUNCTION_NAME are executed when the probe for EVENT executes. The ARGUMENTS are optional values passed into the function.

Functions can be defined anywhere in the script. They may take any

One of the functions needed very often was already introduced in Example 4.1, “Simple SystemTap Script”: the printf function for printing data in a formatted way. When using the printf function, you can specify how arguments should be printed by using a format string. The format string is included in quotation marks and can contain further format specifiers, introduced by a % character.

Which format strings to use depends on your list of arguments. Format strings can have multiple format specifiers—each matching a corresponding argument. Multiple arguments can be separated by a comma.

Example 4.3: printf Function with Format Specifiers
printf ("1%s2(%d3) open\n4", execname(), pid())

1

Start of the format string, indicated by ".

2

String format specifier.

3

Integer format specifier.

4

End of the format string, indicated by ".

The example above prints the current executable name (execname()) as a string and the process ID (pid()) as an integer in brackets. Then, a space, the word open and a line break follow:

[...]
vmware-guestd(2206) open
hald(2360) open
[...]

Apart from the two functions execname()and pid()) used in Example 4.3, “printf Function with Format Specifiers”, a variety of other functions can be used as printf arguments.

Among the most commonly used SystemTap functions are the following:

tid()

ID of the current thread.

pid()

Process ID of the current thread.

uid()

ID of the current user.

cpu()

Current CPU number.

execname()

Name of the current process.

gettimeofday_s()

Number of seconds since Unix epoch (January 1, 1970).

ctime()

Convert time into a string.

pp()

String describing the probe point currently being handled.

thread_indent()

Useful function for organizing print results. It (internally) stores an indentation counter for each thread (tid()). The function takes one argument, an indentation delta, indicating how many spaces to add or remove from the thread's indentation counter. It returns a string with some generic trace data along with an appropriate number of indentation spaces. The generic data returned includes a time stamp (number of microseconds since the initial indentation for the thread), a process name, and the thread ID itself. This allows you to identify what functions were called, who called them, and how long they took.

Call entries and exits often do not immediately precede each other (otherwise it would be easy to match them). In between a first call entry and its exit, usually other call entries and exits are made. The indentation counter helps you match an entry with its corresponding exit as it indents the next function call in case it is not the exit of the previous one. For an example SystemTap script using thread_indent() and the respective output, refer to the SystemTap Tutorial: http://sourceware.org/systemtap/tutorial/Tracing.html#fig:socket-trace.

For more information about supported SystemTap functions, refer to the stapfuncs man page.

4.3.3.2 Other Basic Constructs

Apart from functions, you can use other common constructs in SystemTap handlers, including variables, conditional statements (like if/else, while loops, for loops, arrays or command line arguments.

4.3.3.2.1 Variables

Variables may be defined anywhere in the script. To define one, simply choose a name and assign a value from a function or expression to it:

foo = gettimeofday( )

Then you can use the variable in an expression. From the type of values assigned to the variable, SystemTap automatically infers the type of each identifier (string or number). Any inconsistencies will be reported as errors. In the example above, foo would automatically be classified as a number and could be printed via printf() with the integer format specifier (%d).

However, by default, variables are local to the probe they are used in: They are initialized, used and disposed of at each handler evocation. To share variables between probes, declare them global anywhere in the script. To do so, use the global keyword outside of the probes:

Example 4.4: Using Global Variables
global count_jiffies, count_ms
probe timer.jiffies(100) { count_jiffies ++ }
probe timer.ms(100) { count_ms ++ }
probe timer.ms(12345)
{
  hz=(1000*count_jiffies) / count_ms
  printf ("jiffies:ms ratio %d:%d => CONFIG_HZ=%d\n",
    count_jiffies, count_ms, hz)
  exit ()
  }

This example script computes the CONFIG_HZ setting of the kernel by using timers that count jiffies and milliseconds, then computing accordingly. (A jiffy is the duration of one tick of the system timer interrupt. It is not an absolute time interval unit, since its duration depends on the clock interrupt frequency of the particular hardware platform). With the global statement it is possible to use the variables count_jiffies and count_ms also in the probe timer.ms(12345). With ++ the value of a variable is incremented by 1.

4.3.3.2.2 Conditional Statements

There are several conditional statements that you can use in SystemTap scripts. The following are probably the most common:

If/Else Statements

They are expressed in the following format:

if (CONDITION)1STATEMENT12
else3STATEMENT24

The if statement compares an integer-valued expression to zero. If the condition expression 1 is non-zero, the first statement 2 is executed. If the condition expression is zero, the second statement 4 is executed. The else clause (3 and 4) is optional. Both 2 and 4 can also be statement blocks.

While Loops

They are expressed in the following format:

while (CONDITION)1STATEMENT2

As long as condition is non-zero, the statement 2 is executed. 2 can also be a statement block. It must change a value so condition will eventually be zero.

For Loops

They are a shortcut for while loops and are expressed in the following format:

for (INITIALIZATION1; CONDITIONAL2; INCREMENT3) statement

The expression specified in 1 is used to initialize a counter for the number of loop iterations and is executed before execution of the loop starts. The execution of the loop continues until the loop condition 2 is false. (This expression is checked at the beginning of each loop iteration). The expression specified in 3 is used to increment the loop counter. It is executed at the end of each loop iteration.

Conditional Operators

The following operators can be used in conditional statements:

==:  Is equal to

!=:  Is not equal to

>=:  Is greater than or equal to

<=:  Is less than or equal to

4.4 Example Script

If you have installed the systemtap-docs package, you can find several useful SystemTap example scripts in /usr/share/doc/packages/systemtap/examples.

This section describes a rather simple example script in more detail: /usr/share/doc/packages/systemtap/examples/network/tcp_connections.stp.

Example 4.5: Monitoring Incoming TCP Connections with tcp_connections.stp
#! /usr/bin/env stap

probe begin {
  printf("%6s %16s %6s %6s %16s\n",
         "UID", "CMD", "PID", "PORT", "IP_SOURCE")
}

probe kernel.function("tcp_accept").return?,
      kernel.function("inet_csk_accept").return? {
  sock = $return
  if (sock != 0)
    printf("%6d %16s %6d %6d %16s\n", uid(), execname(), pid(),
           inet_get_local_port(sock), inet_get_ip_source(sock))
}

This SystemTap script monitors the incoming TCP connections and helps to identify unauthorized or unwanted network access requests in real time. It shows the following information for each new incoming TCP connection accepted by the computer:

  • User ID (UID)

  • Command accepting the connection (CMD)

  • Process ID of the command (PID)

  • Port used by the connection (PORT)

  • IP address from which the TCP connection originated (IP_SOUCE)

To run the script, execute

stap /usr/share/doc/packages/systemtap/examples/network/tcp_connections.stp

and follow the output on the screen. To manually stop the script, press CtrlC.

4.5 User Space Probing

For debugging user space applications (like DTrace can do), SUSE Linux Enterprise Server 12 SP3 supports user space probing with SystemTap: Custom probe points can be inserted in any user space application. Thus, SystemTap lets you use both kernel space and user space probes to debug the behavior of the whole system.

To get the required utrace infrastructure and the uprobes kernel module for user space probing, you need to install the kernel-trace package in addition to the packages listed in Section 4.2, “Installation and Setup”.

utrace implements a framework for controlling user space tasks. It provides an interface that can be used by various tracing engines, implemented as loadable kernel modules. The engines register callback functions for specific events, then attach to whichever thread they want to trace. As the callbacks are made from safe places in the kernel, this allows for great leeway in the kinds of processing the functions can do. Various events can be watched via utrace, for example, system call entry and exit, fork(), signals being sent to the task, etc. More details about the utrace infrastructure are available at http://sourceware.org/systemtap/wiki/utrace.

SystemTap includes support for probing the entry into and return from a function in user space processes, probing predefined markers in user space code, and monitoring user-process events.

To check if the currently running kernel provides the needed utrace support, use the following command:

 grep CONFIG_UTRACE /boot/config-`uname -r`

For more details about user space probing, refer to https://sourceware.org/systemtap/SystemTap_Beginners_Guide/userspace-probing.html.

4.6 For More Information

This chapter only provides a short SystemTap overview. Refer to the following links for more information about SystemTap:

http://sourceware.org/systemtap/

SystemTap project home page.

http://sourceware.org/systemtap/wiki/

Huge collection of useful information about SystemTap, ranging from detailed user and developer documentation to reviews and comparisons with other tools, or Frequently Asked Questions and tips. Also contains collections of SystemTap scripts, examples and usage stories and lists recent talks and papers about SystemTap.

http://sourceware.org/systemtap/documentation.html

Features a SystemTap Tutorial, a SystemTap Beginner's Guide, a Tapset Developer's Guide, and a SystemTap Language Reference in PDF and HTML format. Also lists the relevant man pages.

You can also find the SystemTap language reference and SystemTap tutorial in your installed system under /usr/share/doc/packages/systemtap. Example SystemTap scripts are available from the example subdirectory.

5 Kernel Probes

  • Filename: tuning_kprobes.xml
  • ID: cha.tuning.kprobes

Kernel probes are a set of tools to collect Linux kernel debugging and performance information. Developers and system administrators usually use them either to debug the kernel, or to find system performance bottlenecks. The reported data can then be used to tune the system for better performance.

You can insert these probes into any kernel routine, and specify a handler to be invoked after a particular break-point is hit. The main advantage of kernel probes is that you no longer need to rebuild the kernel and reboot the system after you make changes in a probe.

To use kernel probes, you typically need to write or obtain a specific kernel module. Such modules include both the init and the exit function. The init function (such as register_kprobe()) registers one or more probes, while the exit function unregisters them. The registration function defines where the probe will be inserted and which handler will be called after the probe is hit. To register or unregister a group of probes at one time, you can use relevant register_<PROBE_TYPE>probes() or unregister_<PROBE_TYPE>probes() functions.

Debugging and status messages are typically reported with the printk kernel routine. printk is a kernel space equivalent of a user space printf routine. For more information on printk, see Logging kernel messages. Normally, you can view these messages by inspecting the output of the systemd journal (see Chapter 15, journalctl: Query the systemd Journal). For more information on log files, see Chapter 3, Analyzing and Managing System Log Files.

5.1 Supported Architectures

Kernel probes are fully implemented on the following architectures:

  • x86

  • AMD64/Intel 64

  • ARM

  • POWER

Kernel probes are partially implemented on the following architectures:

  • IA64 (does not support probes on instruction slot1)

  • sparc64 (return probes not yet implemented)

5.2 Types of Kernel Probes

There are three types of kernel probes: Kprobes, Jprobes, and Kretprobes. Kretprobes are sometimes called return probes. You can find source code examples of all three type of probes in the Linux kernel. See the directory /usr/src/linux/samples/kprobes/ (package kernel-source).

5.2.1 Kprobes

Kprobes can be attached to any instruction in the Linux kernel. When Kprobes is registered, it inserts a break-point at the first byte of the probed instruction. When the processor hits this break-point, the processor registers are saved, and the processing passes to Kprobes. First, a pre-handler is executed, then the probed instruction is stepped, and, finally a post-handler is executed. The control is then passed to the instruction following the probe point.

5.2.2 Jprobes

Jprobes is implemented through the Kprobes mechanism. It is inserted on a function's entry point and allows direct access to the arguments of the function which is being probed. Its handler routine must have the same argument list and return value as the probed function. To end it, call the jprobe_return() function.

When a jprobe is hit, the processor registers are saved, and the instruction pointer is directed to the jprobe handler routine. The control then passes to the handler with the same register contents as the function being probed. Finally, the handler calls the jprobe_return() function, and switches the control back to the control function.

In general, you can insert multiple probes on one function. Jprobe is, however, limited to only one instance per function.

5.2.3 Return Probe

Return probes are also implemented through Kprobes. When the register_kretprobe() function is called, a kprobe is attached to the entry of the probed function. After hitting the probe, the kernel probes mechanism saves the probed function return address and calls a user-defined return handler. The control is then passed back to the probed function.

Before you call register_kretprobe(), you need to set a maxactive argument, which specifies how many instances of the function can be probed at the same time. If set too low, you will miss a certain number of probes.

5.3 Kprobes API

The programming interface of Kprobes consists of functions which are used to register and unregister all used kernel probes, and associated probe handlers. For a more detailed description of these functions and their arguments, see the information sources in Section 5.5, “For More Information”.

register_kprobe()

Inserts a break-point on a specified address. When the break-point is hit, the pre_handler and post_handler are called.

register_jprobe()

Inserts a break-point in the specified address. The address needs to be the address of the first instruction of the probed function. When the break-point is hit, the specified handler is run. The handler should have the same argument list and return type as the probed.

register_kretprobe()

Inserts a return probe for the specified function. When the probed function returns, a specified handler is run. This function returns 0 on success, or a negative error number on failure.

unregister_kprobe(), unregister_jprobe(), unregister_kretprobe()

Removes the specified probe. You can use it any time after the probe has been registered.

register_kprobes(), register_jprobes(), register_kretprobes()

Inserts each of the probes in the specified array.

unregister_kprobes(), unregister_jprobes(), unregister_kretprobes()

Removes each of the probes in the specified array.

disable_kprobe(), disable_jprobe(), disable_kretprobe()

Disables the specified probe temporarily.

enable_kprobe(), enable_jprobe(), enable_kretprobe()

Temporarily enables disabled probes.

5.4 debugfs Interface

In recent Linux kernels, the Kprobes instrumentation uses the kernel's debugfs interface. It can list all registered probes and globally switch all probes on or off.

5.4.1 Listing Registered Kernel Probes

The list of all currently registered probes is in the /sys/kernel/debug/kprobes/list file.

saturn.example.com:~ # cat /sys/kernel/debug/kprobes/list
c015d71a  k  vfs_read+0x0   [DISABLED]
c011a316  j  do_fork+0x0
c03dedc5  r  tcp_v4_rcv+0x0

The first column lists the address in the kernel where the probe is inserted. The second column prints the type of the probe: k for kprobe, j for jprobe, and r for return probe. The third column specifies the symbol, offset and optional module name of the probe. The following optional columns include the status information of the probe. If the probe is inserted on a virtual address which is not valid anymore, it is marked with [GONE]. If the probe is temporarily disabled, it is marked with [DISABLED].

5.4.2 How to Switch All Kernel Probes On or Off

The /sys/kernel/debug/kprobes/enabled file represents a switch with which you can globally and forcibly turn on or off all the registered kernel probes. To turn them off, simply enter

echo "0" > /sys/kernel/debug/kprobes/enabled

on the command line as root. To turn them on again, enter

echo "1" > /sys/kernel/debug/kprobes/enabled

Note that this way you do not change the status of the probes. If a probe is temporarily disabled, it will not be enabled automatically but will remain in the [DISABLED] state after entering the latter command.

5.5 For More Information

To learn more about kernel probes, look at the following sources of information:

  • Thorough but more technically oriented information about kernel probes is in /usr/src/linux/Documentation/kprobes.txt (package kenrel-source).

  • Examples of all three types of probes (together with related Makefile) are in the /usr/src/linux/samples/kprobes/ directory (package kenrel-source).

  • In-depth information about Linux kernel modules and printk kernel routine is in The Linux Kernel Module Programming Guide

  • Practical but slightly outdated information about the use of kernel probes can be found in Kernel debugging with Kprobes

6 Hardware-Based Performance Monitoring with Perf

  • Filename: tuning_perf.xml
  • ID: cha.perf
Abstract

Perf is an interface to access the performance monitoring unit (PMU) of a processor and to record and display software events such as page faults. It supports system-wide, per-thread, and KVM virtualization guest monitoring.

You can store resulting information in a report. This report contains information about, for example, instruction pointers or what code a thread was executing.

Perf consists of two parts:

  • Code integrated into the Linux kernel that is responsible for instructing the hardware.

  • The perf user space utility that allows you to use the kernel code and helps you analyze gathered data.

6.1 Hardware-Based Monitoring

Performance monitoring means collecting information related to how an application or system performs. This information can be obtained either through software-based means or from the CPU or chipset. Perf integrates both of these methods.

Many modern processors contain a performance monitoring unit (PMU). The design and functionality of a PMU is CPU-specific. For example, the number of registers, counters and features supported will vary by CPU implementation.

Each PMU model consists of a set of registers: the performance monitor configuration (PMC) and the performance monitor data (PMD). Both can be read, but only PMCs are writable. These registers store configuration information and data.

6.2 Sampling and Counting

Perf supports several profiling modes:

  • Counting.  Count the number of occurrences of an event.

  • Event-Based Sampling.  A less exact way of counting: A sample is recorded whenever a certain threshold number of events has occurred.

  • Time-Based Sampling.  A less exact way of counting: A sample is recorded in a defined frequency.

  • Instruction-Based Sampling (AMD64 only).  The processor follows instructions appearing in a given interval and samples which events they produce. This allows following up on individual instructions and seeing which of them is critical to performance.

6.3 Installing Perf

The Perf kernel code is already included with the default kernel. To be able to use the user space utility, install the package perf.

6.4 Perf Subcommands

To gather the required information, the perf tool has several subcommands. This section gives an overview of the most often used commands.

To see help in the form of a man page for any of the subcommands, use either perf helpSUBCOMMAND or man perf-SUBCOMMAND.

perf stat

Start a program and create a statistical overview that is displayed after the program quits. perf stat is used to count events.

perf record

Start a program and create a report with performance counter information. The report is stored as perf.data in the current directory. perf record is used to sample events.

perf report

Display a report that was previously created with perf record.

perf annotate

Display a report file and an annotated version of the executed code. If debug symbols are installed, you will also see the source code displayed.

perf list

List event types that Perf can report with the current kernel and with your CPU. You can filter event types by category—for example, to see hardware events only, use perf list hw.

The man page for perf_event_open has short descriptions for the most important events. For example, to find a description of the event branch-misses, search for BRANCH_MISSES (note the spelling differences):

tux > man perf_event_open | grep -A5 BRANCH_MISSES

Sometimes, events may be ambiguous. Note that the lowercase hardware event names are not the name of raw hardware events but instead the name of aliases created by Perf. These aliases map to differently named but similarly defined hardware events on each supported processor.

For example, the cpu-cycles event is mapped to the hardware event UNHALTED_CORE_CYCLES on Intel processors. On AMD processors, however, it is mapped to the hardware event CPU_CLK_UNHALTED.

Perf also allows measuring raw events specific to your hardware. To look up their descriptions, see the Architecture Software Developer's Manual of your CPU vendor. The relevant documents for AMD64/Intel 64 processors are linked to in Section 6.7, “For More Information”.

perf top

Display system activity as it happens.

perf trace

This command behaves similarly to strace. With this subcommand, you can see which system calls are executed by a particular thread or process and which signals it receives.

6.5 Counting Particular Types of Event

To count the number of occurrences of an event, such as those displayed by perf list, use:

root # perf stat -e EVENT -a

To count multiple types of events at once, list them separated by commas. For example, to count cpu-cycles and instructions, use:

root # perf stat -e cpu-cycles,instructions -a

To stop the session, press CtrlC.

You can also count the number of occurrences of an event within a particular time:

root # perf stat -e EVENT -a -- sleep TIME

Replace TIME by a value in seconds.

6.6 Recording Events Specific to Particular Commands

There are various ways to sample events specific to a particular command:

  • To create a report for a newly invoked command, use:

    root # perf record COMMAND

    Then, use the started process normally. When you quit the process, the Perf session will also stop.

  • To create a report for the entire system while a newly invoked command is running, use:

    root # perf record -a COMMAND

    Then, use the started process normally. When you quit the process, the Perf session will also stop.

  • To create a report for an already running process, use:

    root # perf record -p PID

    Replace PID with a process ID. To stop the session, press CtrlC.

Now you can view the gathered data (perf.data) using:

tux > perf report

This will open a pseudo-graphical interface. To receive help, press H. To quit, press Q.

If you prefer a graphical interface, try the GTK+ interface of Perf:

tux > perf report --gtk

However, note that the GTK+ interface is very limited in functionality.

6.7 For More Information

This chapter only provides a short overview. Refer to the following links for more information:

https://perf.wiki.kernel.org/index.php/Main_Page

The project home page. It also features a tutorial on using perf.

http://www.brendangregg.com/perf.html

Unofficial page with many one-line examples of how to use perf.

http://web.eece.maine.edu/~vweaver/projects/perf_events/

Unofficial page with several resources, mostly relating to the Linux kernel code of Perf and its API. This page includes, for example, a CPU compatibility table and a programming guide.

https://www-ssl.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-vol-3b-part-2-manual.pdf

The Intel Architectures Software Developer's Manual, Volume 3B.

https://support.amd.com/TechDocs/24593.pdf

The AMD Architecture Programmer's Manual, Volume 2.

Chapter 7, OProfile—System-Wide Profiler

Consult this chapter for other performance optimizations.

7 OProfile—System-Wide Profiler

  • Filename: tuning_oprofile.xml
  • ID: cha.tuning.oprofile
Abstract

OProfile is a profiler for dynamic program analysis. It investigates the behavior of a running program and gathers information. This information can be viewed and gives hints for further optimization.

It is not necessary to recompile or use wrapper libraries to use OProfile. Not even a kernel patch is needed. Usually, when profiling an application, a small overhead is expected, depending on the workload and sampling frequency.

7.1 Conceptual Overview

OProfile consists of a kernel driver and a daemon for collecting data. It uses the hardware performance counters provided on many processors. OProfile is capable of profiling all code including the kernel, kernel modules, kernel interrupt handlers, system shared libraries, and other applications.

Modern processors support profiling through the hardware by performance counters. Depending on the processor, there can be many counters and each of these can be programmed with an event to count. Each counter has a value which determines how often a sample is taken. The lower the value, the more often it is used.

During the post-processing step, all information is collected and instruction addresses are mapped to a function name.

7.2 Installation and Requirements

To use OProfile, install the oprofile package that is included with the SLE SDK. OProfile works on AMD64/Intel 64, z Systems, and POWER processors. To find out how to install software from the SDK, refer to Section 14.4, “SUSE Software Development Kit (SDK) 12 SP3.

It is useful to install the *-debuginfo package for the respective application you want to profile. If you want to profile the kernel, you need the debuginfo package as well.

7.3 Available OProfile Utilities

OProfile contains several utilities to handle the profiling process and its profiled data. The following list is a short summary of programs used in this chapter:

opannotate

Outputs annotated source or assembly listings mixed with profile information. An annotated report can be used in combination with addr2line to identify the source file and line where hotspots potentially exist. See man addr2line for more information.

opcontrol

Controls the profiling sessions (start or stop), dumps profile data, and sets up parameters.

ophelp

Lists available events with short descriptions.

opimport

Converts sample database files from a foreign binary format to the native format.

opreport

Generates reports from profiled data.

7.4 Using OProfile

With OProfile, you can profile both the kernel and applications. When profiling the kernel, tell OProfile where to find the vmlinuz* file. Use the --vmlinux option and point it to vmlinuz* (usually in /boot). If you need to profile kernel modules, OProfile does this by default. However, make sure you read http://oprofile.sourceforge.net/doc/kernel-profiling.html.

Applications usually do not need to profile the kernel, therefore you should use the --no-vmlinux option to reduce the amount of information.

7.4.1 Creating a Report

Starting the daemon, collecting data, stopping the daemon, and creating a report.

  1. Open a shell and log in as root.

  2. Decide if you want to profile with or without the Linux kernel:

    1. Profile With the Linux Kernel.  Execute the following commands, because opcontrol can only work with uncompressed images:

      cp /boot/vmlinux-`uname -r`.gz /tmp
      gunzip /tmp/vmlinux*.gz
      opcontrol --vmlinux=/tmp/vmlinux*
    2. Profile Without the Linux Kernel.  Use the following command:

      opcontrol --no-vmlinux

      To see which functions call other functions in the output, additionally use the --callgraph option and set a maximum DEPTH:

      opcontrol --no-vmlinux --callgraph DEPTH
  3. Start the OProfile daemon:

    opcontrol --start
    Using 2.6+ OProfile kernel interface.
    Using log file /var/lib/oprofile/samples/oprofiled.log
    Daemon started.
    Profiler running.
  4. Now start the application you want to profile.

  5. Stop the OProfile daemon:

    opcontrol --stop
  6. Dump the collected data to /var/lib/oprofile/samples:

    opcontrol --dump
  7. Create a report:

    opreport
    Overflow stats not available
    CPU: CPU with timer interrupt, speed 0 MHz (estimated)
    Profiling through timer interrupt
              TIMER:0|
      samples|      %|
    ------------------
        84877 98.3226 no-vmlinux
    ...
  8. Shut down the oprofile daemon:

    opcontrol --shutdown

7.4.2 Getting Event Configurations

The general procedure for event configuration is as follows:

  1. Use first the events CPU-CLK_UNHALTED and INST_RETIRED to find optimization opportunities.

  2. Use specific events to find bottlenecks. To list them, use the command opcontrol --list-events.

If you need to profile certain events, first check the available events supported by your processor with the ophelp command (example output generated from Intel Core i5 CPU):

ophelp
oprofile: available events for CPU type "Intel Architectural Perfmon"

See Intel 64 and IA-32 Architectures Software Developer's Manual
Volume 3B (Document 253669) Chapter 18 for architectural perfmon events
This is a limited set of fallback events because oprofile does not know your CPU
CPU_CLK_UNHALTED: (counter: all))
        Clock cycles when not halted (min count: 6000)
INST_RETIRED: (counter: all))
        number of instructions retired (min count: 6000)
LLC_MISSES: (counter: all))
        Last level cache demand requests from this core that missed the LLC (min count: 6000)
        Unit masks (default 0x41)
        ----------
        0x41: No unit mask
LLC_REFS: (counter: all))
        Last level cache demand requests from this core (min count: 6000)
        Unit masks (default 0x4f)
        ----------
        0x4f: No unit mask
BR_MISS_PRED_RETIRED: (counter: all))
        number of mispredicted branches retired (precise) (min count: 500)

You can get the same output from opcontrol --list-events.

Specify the performance counter events with the option --event. Multiple options are possible. This option needs an event name (from ophelp) and a sample rate, for example:

opcontrol --event=CPU_CLK_UNHALTED:100000
Warning
Warning: Setting Sampling Rates with CPU_CLK_UNHALTED

Setting low sampling rates can seriously impair the system performance while high sample rates can disrupt the system to such a high degree that the data is useless. It is recommended to tune the performance metric for being monitored with and without OProfile and to experimentally determine the minimum sample rate that disrupts the performance the least.

7.5 Using OProfile's GUI

The GUI for OProfile can be started as root with oprof_start, see Figure 7.1, “GUI for OProfile”. Select your events and change the counter, if necessary. Every green line is added to the list of checked events. Hover the mouse over the line to see a help text in the status line below. Use the Configuration tab to set the buffer and CPU size, the verbose option and others. Click Start to execute OProfile.

GUI for OProfile
Figure 7.1: GUI for OProfile

7.6 Generating Reports

Before generating a report, make sure OProfile has dumped your data to the /var/lib/oprofile/samples directory using the command opcontrol --dump. A report can be generated with the commands opreport or opannotate.

Calling opreport without any options gives a complete summary. With an executable as an argument, retrieve profile data only from this executable. If you analyze applications written in C++, use the --demangle smart option.

The opannotate generates output with annotations from source code. Run it with the following options:

opannotate --source \
   --base-dirs=BASEDIR \
   --search-dirs= \
   --output-dir=annotated/ \
   /lib/libfoo.so

The option --base-dir contains a comma separated list of paths which is stripped from debug source files. These paths were searched prior to looking in --search-dirs. The --search-dirs option is also a comma separated list of directories to search for source files.

Note
Note: Inaccuracies in Annotated Source

Because of compiler optimization, code can disappear and appear in a different place. Use the information in http://oprofile.sourceforge.net/doc/debug-info.html to fully understand its implications.

7.7 For More Information

This chapter only provides a short overview. Refer to the following links for more information:

http://oprofile.sourceforge.net

The project home page.

Manpages

Details descriptions about the options of the different tools.

/usr/share/doc/packages/oprofile/oprofile.html

Contains the OProfile manual.

http://developer.intel.com/

Architecture reference for Intel processors.

http://www-01.ibm.com/chips/techlib/techlib.nsf/productfamilies/PowerPC/

Architecture reference for PowerPC64 processors in IBM iSeries, pSeries, and Blade server systems.

Part IV Resource Management

8 General System Resource Management

Tuning the system is not only about optimizing the kernel or getting the most out of your application, it begins with setting up a lean and fast system. The way you set up your partitions and file systems can influence the server's speed. The number of active services and the way routine tasks are scheduled also affects performance.

9 Kernel Control Groups

Kernel Control Groups (abbreviated known as cgroups) are a kernel feature that allows aggregating or partitioning tasks (processes) and all their children into hierarchical organized groups. These hierarchical groups can be configured to show a specialized behavior that helps with tuning the system to make best use of available hardware and network resources.

In the following sections, we often reference kernel documentation such as /usr/src/linux/Documentation/cgroups/. These files are part of the kernel-source package.

This chapter is an overview. To use cgroups properly and to avoid performance implications, you must study the provided references.

10 Automatic Non-Uniform Memory Access (NUMA) Balancing

There are physical limitations to hardware that are encountered when many CPU and lots of memory are required. In this chapter, the important limitation is that there is limited communication bandwidth between the CPUs and the memory. One architecture modification that was introduced to address this is Non-Uniform Memory Access (NUMA).

In this configuration, there are multiple nodes. Each of the nodes contains a subset of all CPUs and memory. The access speed to main memory is determined by the location of the memory relative to the CPU. The performance of a workload depends on the application threads accessing data that is local to the CPU the thread is executing on. Automatic NUMA Balancing is a new feature of SLE 12. Automatic NUMA Balancing migrates data on demand to memory nodes that are local to the CPU accessing that data. Depending on the workload, this can dramatically boost performance when using NUMA hardware.

11 Power Management

Power management aims at reducing operating costs for energy and cooling systems while at the same time keeping the performance of a system at a level that matches the current requirements. Thus, power management is always a matter of balancing the actual performance needs and power saving options for a system. Power management can be implemented and used at different levels of the system. A set of specifications for power management functions of devices and the operating system interface to them has been defined in the Advanced Configuration and Power Interface (ACPI). As power savings in server environments can primarily be achieved at the processor level, this chapter introduces some main concepts and highlights some tools for analyzing and influencing relevant parameters.

8 General System Resource Management

  • Filename: tuning_systemresources.xml
  • ID: cha.tuning.resources
Abstract

Tuning the system is not only about optimizing the kernel or getting the most out of your application, it begins with setting up a lean and fast system. The way you set up your partitions and file systems can influence the server's speed. The number of active services and the way routine tasks are scheduled also affects performance.

8.1 Planning the Installation

A carefully planned installation ensures that the system is set up exactly as you need it for the given purpose. It also saves considerable time when fine tuning the system. All changes suggested in this section can be made in the Installation Settings step during the installation. See Section 6.15, “Installation Settings” for details.

8.1.1 Partitioning

Depending on the server's range of applications and the hardware layout, the partitioning scheme can influence the machine's performance (although to a lesser extent only). It is beyond the scope of this manual to suggest different partitioning schemes for particular workloads. However, the following rules will positively affect performance. They do not apply when using an external storage system.

  • Make sure there always is some free space available on the disk, since a full disk delivers inferior performance

  • Disperse simultaneous read and write access onto different disks by, for example:

    • using separate disks for the operating system, data, and log files

    • placing a mail server's spool directory on a separate disk

    • distributing the user directories of a home server between different disks

8.1.2 Installation Scope

The installation scope has no direct influence on the machine's performance, but a carefully chosen scope of packages has advantages. It is recommended to install the minimum of packages needed to run the server. A system with a minimum set of packages is easier to maintain and has fewer potential security issues. Furthermore, a tailor made installation scope also ensures that no unnecessary services are started by default.

SUSE Linux Enterprise Server lets you customize the installation scope on the Installation Summary screen. By default, you can select or remove preconfigured patterns for specific tasks, but it is also possible to start the YaST Software Manager for a fine-grained package-based selection.

One or more of the following default patterns may not be needed in all cases:

GNOME Desktop Environment

Servers rarely need a full desktop environment. In case a graphical environment is needed, a more economical solution such as IceWM can be sufficient.

X Window System

When solely administrating the server and its applications via command line, consider not installing this pattern. However, keep in mind that it is needed to run GUI applications from a remote machine. If your application is managed by a GUI or if you prefer the GUI version of YaST, keep this pattern.

Print Server

This pattern is only needed if you want to print from the machine.

8.1.3 Default Target

A running X Window System consumes many resources and is rarely needed on a server. It is strongly recommended to start the system in target multi-user.target. You will still be able to remotely start graphical applications.

8.2 Disabling Unnecessary Services

The default installation starts several services (the number varies with the installation scope). Since each service consumes resources, it is recommended to disable the ones not needed. Run YaST › System › Services Manager to start the services management module.

If you are using the graphical version of YaST, you can click the column headlines to sort the list of services. Use this to get an overview of which services are currently running. Use the Start/Stop button to disable the service for the running session. To permanently disable it, use the Enable/Disable button.

The following list shows services that are started by default after the installation of SUSE Linux Enterprise Server. Check which of the components you need, and disable the others:

alsasound

Loads the Advanced Linux Sound System.

auditd

A daemon for the Audit system (see Part VI, “The Linux Audit Framework for details). Disable this if you do not use Audit.

bluez-coldplug

Handles cold plugging of Bluetooth dongles.

cups

A printer daemon.

java.binfmt_misc

Enables the execution of *.class or *.jar Java programs.

nfs

Services needed to mount NFS.

smbfs

Services needed to mount SMB/CIFS file systems from a Windows* server.

splash / splash_early

Shows the splash screen on start-up.

8.3 File Systems and Disk Access

Hard disks are the slowest components in a computer system and therefore often the cause for a bottleneck. Using the file system that best suits your workload helps to improve performance. Using special mount options or prioritizing a process's I/O priority are further means to speed up the system.

8.3.1 File Systems

SUSE Linux Enterprise Server ships with several file systems, including BtrFS, Ext4, Ext3, Ext2, ReiserFS, and XFS. Each file system has its own advantages and disadvantages. Refer to Chapter 1, Overview of File Systems in Linux for detailed information.

8.3.1.1 NFS

NFS (Version 3) tuning is covered in detail in the NFS Howto at http://nfs.sourceforge.net/nfs-howto/. The first thing to experiment with when mounting NFS shares is increasing the read write blocksize to 32768 by using the mount options wsize and rsize.

8.3.2 Time Stamp Update Policy

Each file and directory in a file system has three time stamps associated with it: a time when the file was last read called access time, a time when the file data was last modified called modification time, and a time when the file metadata was last modified called change time. Keeping access time always up to date has significant performance overhead since every read-only access will incur a write operation. Thus by default every file system updates access time only if current file access time is older than a day or if it is older than file modification or change time. This feature is called relative access time and the corresponding mount option is relatime. Updates of access time can be completely disabled using the noatime mount option, however you need to verify your applications do not use it. This can be true for file and Web servers or for network storage. If the default relative access time update policy is not suitable for your applications, use the strictatime mount option.

Some file systems (for example Ext4) also support lazy time stamp updates. When this feature is enabled using the lazytime mount option, updates of all time stamps happen in memory but they are not written to disk. That happens only in response to fsync or sync system calls, when the file information is written due to another reason such as file size update, when time stamps are older than 24 hours, or when cached file information needs to be evicted from memory.

To update mount options used for a file system, either edit /etc/fstab directly, or use the Fstab Options dialog when editing or adding a partition with the YaST Partitioner.

8.3.3 Prioritizing Disk Access with ionice

The ionice command lets you prioritize disk access for single processes. This enables you to give less I/O priority to background processes with heavy disk access that are not time-critical, such as backup jobs. ionice also lets you raise the I/O priority for a specific process to make sure this process always has immediate access to the disk. The caveat of this feature is that standard writes are cached in the page cache and are written back to persistent storage only later by an independent kernel process. Thus the I/O priority setting generally does not apply for these writes. Also be aware that I/O class and priority setting is obeyed only by CFQ I/O scheduler (refer to Section 12.2, “Available I/O Elevators”). You can set the following three scheduling classes:

Idle

A process from the idle scheduling class is only granted disk access when no other process has asked for disk I/O.

Best effort

The default scheduling class used for any process that has not asked for a specific I/O priority. Priority within this class can be adjusted to a level from 0 to 7 (with 0 being the highest priority). Programs running at the same best-effort priority are served in a round-robin fashion. Some kernel versions treat priority within the best-effort class differently—for details, refer to the ionice(1) man page.

Real-time

Processes in this class are always granted disk access first. Fine-tune the priority level from 0 to 7 (with 0 being the highest priority). Use with care, since it can starve other processes.

For more details and the exact command syntax refer to the ionice(1) man page. If you need more reliable control over bandwidth available to each application, use Kernel Control Groups as described in Section 9.3, “Control Group Subsystems”.

9 Kernel Control Groups

  • Filename: tuning_cgroups.xml
  • ID: cha.tuning.cgroups
Abstract

Kernel Control Groups (abbreviated known as cgroups) are a kernel feature that allows aggregating or partitioning tasks (processes) and all their children into hierarchical organized groups. These hierarchical groups can be configured to show a specialized behavior that helps with tuning the system to make best use of available hardware and network resources.

In the following sections, we often reference kernel documentation such as /usr/src/linux/Documentation/cgroups/. These files are part of the kernel-source package.

This chapter is an overview. To use cgroups properly and to avoid performance implications, you must study the provided references.

9.1 Technical Overview and Definitions

The following terms are used in this chapter:

  • cgroup is another name for Control Groups.

  • In a cgroup there is a set of tasks (processes) associated with a set of subsystems that act as parameters constituting an environment for the tasks.

  • Subsystems provide the parameters that can be assigned and define CPU sets, freezer, or—more general—resource controllers for memory, disk I/O, network traffic, etc.

  • cgroups are organized in a tree-structured hierarchy. There can be more than one hierarchy in the system. You use a different or alternate hierarchy to cope with specific situations.

  • Every task running in the system is in exactly one of the cgroups in the hierarchy.

9.2 Scenario

See the following resource planning scenario for a better understanding (source: /usr/src/linux/Documentation/cgroups/cgroups.txt):

Resource Planning
Figure 9.1: Resource Planning

Web browsers such as Firefox will be part of the Web network class, while the NFS daemons such as (k)nfsd will be part of the NFS network class. On the other side, Firefox will share appropriate CPU and memory classes depending on whether a professor or student started it.

9.3 Control Group Subsystems

The following subsystems are available: cpuset, cpu, cpuacct, memory, devices, freezer, net_cls, net_prio, blkio, perf_event, and hugetlbt.

Either mount each subsystem separately, for example:

mkdir /cpuset /cpu
mount -t cgroup -o cpuset      none /cpuset
mount -t cgroup -o cpu,cpuacct none /cpu

or all subsystems in one go; you can use an arbitrary device name (for example none), which will appear in /proc/mounts, for example:

mount -t cgroup none /sys/fs/cgroup

Some additional information on available subsystems:

net_cls (Identification)

The Network classifier cgroup helps with providing identification for controlling processes such as Traffic Controller (tc) or Netfilter (iptables). These controller tools can act on tagged network packets.

For more information, see /usr/src/linux/Documentation/cgroups/net_cls.txt.

net_prio (Identification)

The Network priority cgroup helps with setting the priority of network packets.

For more information, see /usr/src/linux/Documentation/cgroups/net_prio.txt.

devices (Isolation)

A system administrator can provide a list of devices that can be accessed by processes under cgroups.

It limits access to a device or a file system on a device to only tasks that belong to the specified cgroup. For more information, see /usr/src/linux/Documentation/cgroups/devices.txt.

freezer (Control)

The freezer subsystem is useful for high-performance computing clusters (HPC clusters). Use it to freeze (stop) all tasks in a group or to stop tasks, if they reach a defined checkpoint. For more information, see /usr/src/linux/Documentation/cgroups/freezer-subsystem.txt.

Here are basic commands to use the freezer subsystem:

mount -t cgroup -o freezer freezer /freezer
# Create a child cgroup:
mkdir /freezer/0
# Put a task into this cgroup:
echo $task_pid > /freezer/0/tasks
# Freeze it:
echo FROZEN > /freezer/0/freezer.state
# Unfreeze (thaw) it:
echo THAWED > /freezer/0/freezer.state
perf_event (Control)

perf_event collects performance data.

cpuset (Isolation)

Use cpuset to tie processes to system subsets of CPUs and memory (memory nodes). For an example, see Section 9.4.2, “Example: Cpusets”.

cpuacct (Accounting)

The CPU accounting controller groups tasks using cgroups and accounts the CPU usage of these groups. For more information, see /usr/src/linux/Documentation/cgroups/cpuacct.txt.

memory (Resource Control)
  • Tracking or limiting memory usage of user space processes.

  • Control swap usage by setting swapaccount=1 as a kernel boot parameter.

  • Limit LRU (Least Recently Used) pages.

  • Anonymous and file cache.

  • No limits for kernel memory.

  • Maybe in another subsystem if needed.

Note
Note: Protection from Memory Pressure

Memory cgroup now offers a mechanism allowing easier workload opt-in isolation. Memory cgroup can define its so called low limit (memory.low_limit_in_bytes), which works as a protection from memory pressure. For workloads that need to be isolated from outside memory management activity, the value should be set to the expected Resident Set Size (RSS) plus some head room. If a memory pressure condition triggers on the system and the particular group is still under its low limit, its memory is protected from reclaim. As a result, workloads outside of the cgroup do not need the aforementioned capping.

For more information, see /usr/src/linux/Documentation/cgroups/memory.txt.

hugetlb (Resource Control)

The HugeTLB controller manages the memory allocated to huge pages.

For more information, see /usr/src/linux/Documentation/cgroups/hugetlb.txt.

cpu (Control)

Share CPU bandwidth between groups with the group scheduling function of CFS (the scheduler). Mechanically complicated.

Blkio (Resource Control)

The Block IO controller is available as a disk I/O controller. With the blkio controller you can currently set policies for proportional bandwidth and for throttling.

These are the basic commands to configure proportional weight division of bandwidth by setting weight values in blkio.weight:

# Setup in /sys/fs/cgroup
mkdir /sys/fs/cgroup/blkio
mount -t cgroup -o blkio none /sys/fs/cgroup/blkio
# Start two cgroups
mkdir -p /sys/fs/cgroup/blkio/group1 /sys/fs/cgroup/blkio/group2
# Set weights
echo 1000 > /sys/fs/cgroup/blkio/group1/blkio.weight
echo  500 > /sys/fs/cgroup/blkio/group2/blkio.weight
# Write the PIDs of the processes to be controlled to the
# appropriate groups
COMMAND1 &
echo $! > /sys/fs/cgroup/blkio/group1/tasks

COMMAND2 &
echo $! > /sys/fs/cgroup/blkio/group2/tasks

These are the basic commands to configure throttling or upper limit policy by setting values in blkio.throttle.read_bps_device for reads and blkio.throttle.write_bps_device for writes:

# Setup in /sys/fs/cgroup
mkdir /sys/fs/cgroup/blkio
mount -t cgroup -o blkio none /sys/fs/cgroup/blkio
# Bandwidth rate of a device for the root group; format:
# <major>:<minor>  <byes_per_second>
echo "8:16  1048576" > /sys/fs/cgroup/blkio/blkio.throttle.read_bps_device

For more information about caveats, usage scenarios, and additional parameters, see /usr/src/linux/Documentation/cgroups/blkio-controller.txt.

9.4 Using Controller Groups

9.4.1 Prerequisites

To conveniently use cgroups, install the following additional packages:

  • libcgroup-tools — basic user space tools to simplify resource management

  • libcgroup1 — control groups management library

  • cpuset — contains the cset to manipulate cpusets

  • libcpuset1 — C API to cpusets

  • kernel-source — only needed for documentation purposes

9.4.2 Example: Cpusets

With the command line proceed as follows:

  1. To determine the number of CPUs and memory nodes see /proc/cpuinfo and /proc/zoneinfo.

  2. Create the cpuset hierarchy as a virtual file system (source: /usr/src/linux/Documentation/cgroups/cpusets.txt):

    mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset
    cd /sys/fs/cgroup/cpuset
    mkdir Charlie
    cd Charlie
    # List of CPUs in this cpuset:
    echo 2-3 > cpuset.cpus
    # List of memory nodes in this cpuset:
    echo 1 > cpuset.mems
    echo $$ > tasks
    # The subshell 'sh' is now running in cpuset Charlie
    # The next line should display '/Charlie'
    cat /proc/self/cpuset
  3. Remove the cpuset using shell commands:

    rmdir /sys/fs/cgroup/cpuset/Charlie

    This fails as long as this cpuset is in use. First, you must remove the inside cpusets or tasks (processes) that belong to it. Check it with:

    cat /sys/fs/cgroup/cpuset/Charlie/tasks

For background information and additional configuration flags, see /usr/src/linux/Documentation/cgroups/cpusets.txt.

With the cset tool, proceed as follows:

# Determine the number of CPUs and memory nodes
cset set --list
# Creating the cpuset hierarchy
cset set --cpu=2-3 --mem=1 --set=Charlie
# Starting processes in a cpuset
cset proc --set Charlie --exec -- stress -c 1 &
# Moving existing processes to a cpuset
cset proc --move --pid PID --toset=Charlie
# List task in a cpuset
cset proc --list --set Charlie
# Removing a cpuset
cset set --destroy Charlie

9.4.3 Example: cgroups

Using shell commands, proceed as follows:

  1. Create the cgroups hierarchy:

    mount -t cgroup cgroup /sys/fs/cgroup
    cd /sys/fs/cgroup/cpuset/cgroup
    mkdir priority
    cd priority
    cat cpu.shares
  2. Understanding cpu.shares:

    • 1024 is the default (for more information, see /Documentation/scheduler/sched-design-CFS.txt) = 50% usage

    • 1524 = 60% usage

    • 2048 = 67% usage

    • 512 = 40% usage

  3. Changing cpu.shares

    echo 1024 > cpu.shares

9.4.4 Setting Directory and File Permissions

This is a simple example. Use the following in /etc/cgconfig.conf:

group foo {
        perm {
                task {
                        uid = root;
                        gid = users;
                        fperm = 660;
                }
                admin {
                        uid = root;
                        gid = root;
                        fperm = 600;
                        dperm = 750;
                }
        }
}

mount {
        cpu = /mnt/cgroups/cpu;
}

Then start the cgconfig service and stat /mnt/cgroups/cpu/foo/tasks which should show the permissions mask 660 with root as an owner and users as a group. stat /mnt/cgroups/cpu/foo/ should be 750 and all files (but tasks) should have the mask 600. Note that fperm is applied on top of existing file permissions as a mask.

For more information, see the cgconfig.conf man page.

9.5 For More Information

10 Automatic Non-Uniform Memory Access (NUMA) Balancing

  • Filename: tuning_numactl.xml
  • ID: cha.tuning.numactl
Abstract

There are physical limitations to hardware that are encountered when many CPU and lots of memory are required. In this chapter, the important limitation is that there is limited communication bandwidth between the CPUs and the memory. One architecture modification that was introduced to address this is Non-Uniform Memory Access (NUMA).

In this configuration, there are multiple nodes. Each of the nodes contains a subset of all CPUs and memory. The access speed to main memory is determined by the location of the memory relative to the CPU. The performance of a workload depends on the application threads accessing data that is local to the CPU the thread is executing on. Automatic NUMA Balancing is a new feature of SLE 12. Automatic NUMA Balancing migrates data on demand to memory nodes that are local to the CPU accessing that data. Depending on the workload, this can dramatically boost performance when using NUMA hardware.

10.1 Implementation

Automatic NUMA balancing happens in three basic steps:

  1. A task scanner periodically scans a portion of a task's address space and marks the memory to force a page fault when the data is next accessed.

  2. The next access to the data will result in a NUMA Hinting Fault. Based on this fault, the data can be migrated to a memory node associated with the task accessing the memory.

  3. To keep a task, the CPU it is using and the memory it is accessing together, the scheduler groups tasks that share data.

The unmapping of data and page fault handling incurs overhead. However, commonly the overhead will be offset by threads accessing data associated with the CPU.

10.2 Configuration

Static configuration has been the recommended way of tuning workloads on NUMA hardware for some time. To do this, memory policies can be set with numactl, taskset or cpusets. NUMA-aware applications can use special APIs. In cases where the static policies have already been created, automatic NUMA balancing should be disabled as the data access should already be local.

numactl --hardware will show the memory configuration of the machine and whether it supports NUMA or not. This is example output from a 4-node machine.

tux > numactl --hardware
available: 4 nodes (0-3)
node 0 cpus: 0 4 8 12 16 20 24 28 32 36 40 44
node 0 size: 16068 MB
node 0 free: 15909 MB
node 1 cpus: 1 5 9 13 17 21 25 29 33 37 41 45
node 1 size: 16157 MB
node 1 free: 15948 MB
node 2 cpus: 2 6 10 14 18 22 26 30 34 38 42 46
node 2 size: 16157 MB
node 2 free: 15981 MB
node 3 cpus: 3 7 11 15 19 23 27 31 35 39 43 47
node 3 size: 16157 MB
node 3 free: 16028 MB
node distances:
node   0   1   2   3
  0:  10  20  20  20
  1:  20  10  20  20
  2:  20  20  10  20
  3:  20  20  20  10

Automatic NUMA balancing can be enabled or disabled for the current session by writing 1 or 0 to /proc/sys/kernel/numa_balancing which will enable or disable the feature respectively. To permanently enable or disable it, use the kernel command line option numa_balancing=[enable|disable].

If Automatic NUMA Balancing is enabled, the task scanner behavior can be configured. The task scanner balances the overhead of Automatic NUMA Balancing with the amount of time it takes to identify the best placement of data.

numa_balancing_scan_delay_ms

The amount of CPU time a thread must consume before its data is scanned. This prevents creating overhead because of short-lived processes.

numa_balancing_scan_period_min_ms and numa_balancing_scan_period_max_ms

Controls how frequently a task's data is scanned. Depending on the locality of the faults the scan rate will increase or decrease. These settings control the min and max scan rates.

numa_balancing_scan_size_mb

Controls how much address space is scanned when the task scanner is active.

10.3 Monitoring

The most important task is to assign metrics to your workload and measure the performance with Automatic NUMA Balancing enabled and disabled to measure the impact. Profiling tools can be used to monitor local and remote memory accesses if the CPU supports such monitoring. Automatic NUMA Balancing activity can be monitored via the following parameters in /proc/vmstat:

numa_pte_updates

The amount of base pages that were marked for NUMA hinting faults.

numa_huge_pte_updates

The amount of transparent huge pages that were marked for NUMA hinting faults. In combination with numa_pte_updates the total address space that was marked can be calculated.

numa_hint_faults

Records how many NUMA hinting faults were trapped.

numa_hint_faults_local

Shows how many of the hinting faults were to local nodes. In combination with numa_hint_faults, the percentage of local versus remote faults can be calculated. A high percentage of local hinting faults indicates that the workload is closer to being converged.

numa_pages_migrated

Records how many pages were migrated because they were misplaced. As migration is a copying operation, it contributes the largest part of the overhead created by NUMA balancing.

10.4 Impact

The following illustrates a simple test case of a 4-node NUMA machine running the SpecJBB 2005 using a single instance of the JVM with no static tuning around memory policies. Note, however, that the impact for each workload will vary and that this example is based on a pre-release version of SUSE Linux Enterprise Server 12.

            Balancing disabled      Balancing enabled
TPut 1      26629.00 (  0.00%)     26507.00 ( -0.46%)
TPut 2      55841.00 (  0.00%)     53592.00 ( -4.03%)
TPut 3      86078.00 (  0.00%)     86443.00 (  0.42%)
TPut 4     116764.00 (  0.00%)    113272.00 ( -2.99%)
TPut 5     143916.00 (  0.00%)    141581.00 ( -1.62%)
TPut 6     166854.00 (  0.00%)    166706.00 ( -0.09%)
TPut 7     195992.00 (  0.00%)    192481.00 ( -1.79%)
TPut 8     222045.00 (  0.00%)    227143.00 (  2.30%)
TPut 9     248872.00 (  0.00%)    250123.00 (  0.50%)
TPut 10    270934.00 (  0.00%)    279314.00 (  3.09%)
TPut 11    297217.00 (  0.00%)    301878.00 (  1.57%)
TPut 12    311021.00 (  0.00%)    326048.00 (  4.83%)
TPut 13    324145.00 (  0.00%)    346855.00 (  7.01%)
TPut 14    345973.00 (  0.00%)    378741.00 (  9.47%)
TPut 15    354199.00 (  0.00%)    394268.00 ( 11.31%)
TPut 16    378016.00 (  0.00%)    426782.00 ( 12.90%)
TPut 17    392553.00 (  0.00%)    437772.00 ( 11.52%)
TPut 18    396630.00 (  0.00%)    456715.00 ( 15.15%)
TPut 19    399114.00 (  0.00%)    484020.00 ( 21.27%)
TPut 20    413907.00 (  0.00%)    493618.00 ( 19.26%)
TPut 21    413173.00 (  0.00%)    510386.00 ( 23.53%)
TPut 22    420256.00 (  0.00%)    521016.00 ( 23.98%)
TPut 23    425581.00 (  0.00%)    536214.00 ( 26.00%)
TPut 24    429052.00 (  0.00%)    532469.00 ( 24.10%)
TPut 25    426127.00 (  0.00%)    526548.00 ( 23.57%)
TPut 26    422428.00 (  0.00%)    531994.00 ( 25.94%)
TPut 27    424378.00 (  0.00%)    488340.00 ( 15.07%)
TPut 28    419338.00 (  0.00%)    543016.00 ( 29.49%)
TPut 29    403347.00 (  0.00%)    529178.00 ( 31.20%)
TPut 30    408681.00 (  0.00%)    510621.00 ( 24.94%)
TPut 31    406496.00 (  0.00%)    499781.00 ( 22.95%)
TPut 32    404931.00 (  0.00%)    502313.00 ( 24.05%)
TPut 33    397353.00 (  0.00%)    522418.00 ( 31.47%)
TPut 34    382271.00 (  0.00%)    491989.00 ( 28.70%)
TPut 35    388965.00 (  0.00%)    493012.00 ( 26.75%)
TPut 36    374702.00 (  0.00%)    502677.00 ( 34.15%)
TPut 37    367578.00 (  0.00%)    500588.00 ( 36.19%)
TPut 38    367121.00 (  0.00%)    496977.00 ( 35.37%)
TPut 39    355956.00 (  0.00%)    489430.00 ( 37.50%)
TPut 40    350855.00 (  0.00%)    487802.00 ( 39.03%)
TPut 41    345001.00 (  0.00%)    468021.00 ( 35.66%)
TPut 42    336177.00 (  0.00%)    462260.00 ( 37.50%)
TPut 43    329169.00 (  0.00%)    467906.00 ( 42.15%)
TPut 44    329475.00 (  0.00%)    470784.00 ( 42.89%)
TPut 45    323845.00 (  0.00%)    450739.00 ( 39.18%)
TPut 46    323878.00 (  0.00%)    435457.00 ( 34.45%)
TPut 47    310524.00 (  0.00%)    403914.00 ( 30.07%)
TPut 48    311843.00 (  0.00%)    459017.00 ( 47.19%)

                        Balancing Disabled        Balancing Enabled
 Expctd Warehouse          48.00 (  0.00%)          48.00 (  0.00%)
 Expctd Peak Bops      310524.00 (  0.00%)      403914.00 ( 30.07%)
 Actual Warehouse          25.00 (  0.00%)          29.00 ( 16.00%)
 Actual Peak Bops      429052.00 (  0.00%)      543016.00 ( 26.56%)
 SpecJBB Bops            6364.00 (  0.00%)        9368.00 ( 47.20%)
 SpecJBB Bops/JVM        6364.00 (  0.00%)        9368.00 ( 47.20%)

Automatic NUMA Balancing simplifies tuning workloads for high performance on NUMA machines. Where possible, it is still recommended to statically tune the workload to partition it within each node. However, in all other cases, automatic NUMA balancing should boost performance.

11 Power Management

  • Filename: tuning_power.xml
  • ID: cha.tuning.power
Abstract

Power management aims at reducing operating costs for energy and cooling systems while at the same time keeping the performance of a system at a level that matches the current requirements. Thus, power management is always a matter of balancing the actual performance needs and power saving options for a system. Power management can be implemented and used at different levels of the system. A set of specifications for power management functions of devices and the operating system interface to them has been defined in the Advanced Configuration and Power Interface (ACPI). As power savings in server environments can primarily be achieved at the processor level, this chapter introduces some main concepts and highlights some tools for analyzing and influencing relevant parameters.

11.1 Power Management at CPU Level

At the CPU level, you can control power usage in various ways. For example by using idling power states (C-states), changing CPU frequency (P-states), and throttling the CPU (T-states). The following sections give a short introduction to each approach and its significance for power savings. Detailed specifications can be found at http://www.acpi.info/spec.htm.

11.1.1 C-States (Processor Operating States)

Modern processors have several power saving modes called C-states. They reflect the capability of an idle processor to turn off unused components to save power.

When a processor is in the C0 state, it is executing instructions. A processor running in any other C-state is idle. The higher the C number, the deeper the CPU sleep mode: more components are shut down to save power. Deeper sleep states can save large amounts of energy. Their downside is that they introduce latency. This means, it takes more time for the CPU to go back to C0. Depending on workload (threads waking up, triggering CPU usage and then going back to sleep again for a short period of time) and hardware (for example, interrupt activity of a network device), disabling the deepest sleep states can significantly increase overall performance. For details on how to do so, refer to Section 11.3.2, “Viewing Kernel Idle Statistics with cpupower.

Some states also have submodes with different power saving latency levels. Which C-states and submodes are supported depends on the respective processor. However, C1 is always available.

Table 11.1, “C-States” gives an overview of the most common C-states.

Table 11.1: C-States

Mode

Definition

C0

Operational state. CPU fully turned on.

C1

First idle state. Stops CPU main internal clocks via software. Bus interface unit and APIC are kept running at full speed.

C2

Stops CPU main internal clocks via hardware. State in which the processor maintains all software-visible states, but may take longer to wake up through interrupts.

C3

Stops all CPU internal clocks. The processor does not need to keep its cache coherent, but maintains other states. Some processors have variations of the C3 state that differ in how long it takes to wake the processor through interrupts.

To avoid needless power consumption, it is recommended to test your workloads with deep sleep states enabled versus deep sleep states disabled. For more information, refer to Section 11.3.2, “Viewing Kernel Idle Statistics with cpupower or the cpupower-idle-set(1) man page.

11.1.2 P-States (Processor Performance States)

While a processor operates (in C0 state), it can be in one of several CPU performance states (P-states). Whereas C-states are idle states (all but C0), P-states are operational states that relate to CPU frequency and voltage.

The higher the P-state, the lower the frequency and voltage at which the processor runs. The number of P-states is processor-specific and the implementation differs across the various types. However, P0 is always the highest-performance state (except for Section 11.1.3, “Turbo Features”). Higher P-state numbers represent slower processor speeds and lower power consumption. For example, a processor in P3 state runs more slowly and uses less power than a processor running in the P1 state. To operate at any P-state, the processor must be in the C0 state, which means that it is working and not idling. The CPU P-states are also defined in the ACPI specification, see http://www.acpi.info/spec.htm.

C-states and P-states can vary independently of one another.

11.1.3 Turbo Features

Turbo features allow to dynamically overtick active CPU cores while other cores are in deep sleep states. This increases the performance of active threads while still complying with Thermal Design Power (TDP) limits.

However, the conditions under which a CPU core can use turbo frequencies are architecture-specific. Learn how to evaluate the efficiency of those new features in Section 11.3, “The cpupower Tools”.

11.2 In-Kernel Governors

The in-kernel governors belong to the Linux kernel CPUfreq infrastructure and can be used to dynamically scale processor frequencies at runtime. You can think of the governors as a sort of preconfigured power scheme for the CPU. The CPUfreq governors use P-states to change frequencies and lower power consumption. The dynamic governors can switch between CPU frequencies, based on CPU usage, to allow for power savings while not sacrificing performance.

The following governors are available with the CPUfreq subsystem:

Performance Governor

The CPU frequency is statically set to the highest possible for maximum performance. Consequently, saving power is not the focus of this governor.

See also Section 11.4.1, “Tuning Options for P-States”.

Powersave Governor

The CPU frequency is statically set to the lowest possible. This can have severe impact on the performance, as the system will never rise above this frequency no matter how busy the processors are. An important exception is the intel_pstate which defaults to the powersave mode. This is due to a hardware-specific decision but functionally it operates similarly to the on-demand governor.

However, using this governor often does not lead to the expected power savings as the highest savings can usually be achieved at idle through entering C-states. With the powersave governor, processes run at the lowest frequency and thus take longer to finish. This means it takes longer until the system can go into an idle C-state.

Tuning options: The range of minimum frequencies available to the governor can be adjusted (for example, with the cpupower command line tool).

On-demand Governor

The kernel implementation of a dynamic CPU frequency policy: The governor monitors the processor usage. When it exceeds a certain threshold, the governor will set the frequency to the highest available. If the usage is less than the threshold, the next lowest frequency is used. If the system continues to be underemployed, the frequency is again reduced until the lowest available frequency is set.

Important
Important: Drivers and In-kernel Governors

Not all drivers use the in-kernel governors to dynamically scale power frequency at runtime. For example, the intel_pstate driver adjusts power frequency itself. Use the cpupower frequency-info command to find out which driver your system uses.

11.3 The cpupower Tools

The cpupower tools are designed to give an overview of all CPU power-related parameters that are supported on a given machine, including turbo (or boost) states. Use the tool set to view and modify settings of the kernel-related CPUfreq and cpuidle systems and other settings not related to frequency scaling or idle states. The integrated monitoring framework can access both kernel-related parameters and hardware statistics. Therefore, it is ideally suited for performance benchmarks. It also helps you to identify the dependencies between turbo and idle states.

After installing the cpupower package, view the available cpupower subcommands with cpupower --help. Access the general man page with man cpupower, and the man pages of the subcommands with man cpupower-SUBCOMMAND.

11.3.1 Viewing Current Settings with cpupower

The cpupower frequency-info command shows the statistics of the cpufreq driver used in the kernel. Additionally, it shows if turbo (boost) states are supported and enabled in the BIOS. Run without any options, it shows an output similar to the following:

Example 11.1: Example Output of cpupower frequency-info
root # cpupower frequency-info
analyzing CPU 0:
  driver: intel_pstate
  CPUs which run at the same hardware frequency: 0
  CPUs which need to have their frequency coordinated by software: 0
  maximum transition latency: 0.97 ms.
  hardware limits: 1.20 GHz - 3.80 GHz
  available cpufreq governors: performance, powersave
  current policy: frequency should be within 1.20 GHz and 3.80 GHz.
                  The governor "powersave" may decide which speed to use
                  within this range.
  current CPU frequency is 3.40 GHz (asserted by call to hardware).
  boost state support:
    Supported: yes
    Active: yes
    3500 MHz max turbo 4 active cores
    3600 MHz max turbo 3 active cores
    3600 MHz max turbo 2 active cores
    3800 MHz max turbo 1 active cores

To get the current values for all CPUs, use cpupower -c all frequency-info.

11.3.2 Viewing Kernel Idle Statistics with cpupower

The idle-info subcommand shows the statistics of the cpuidle driver used in the kernel. It works on all architectures that use the cpuidle kernel framework.

Example 11.2: Example Output of cpupower idle-info
root # cpupower idle-info
CPUidle driver: intel_idle
CPUidle governor: menu

Analyzing CPU 0:
Number of idle states: 6
Available idle states: POLL C1-SNB C1E-SNB C3-SNB C6-SNB C7-SNB
POLL:
Flags/Description: CPUIDLE CORE POLL IDLE
Latency: 0
Usage: 163128
Duration: 17585669
C1-SNB:
Flags/Description: MWAIT 0x00
Latency: 2
Usage: 16170005
Duration: 697658910
C1E-SNB:
Flags/Description: MWAIT 0x01
Latency: 10
Usage: 4421617
Duration: 757797385
C3-SNB:
Flags/Description: MWAIT 0x10
Latency: 80
Usage: 2135929
Duration: 735042875
C6-SNB:
Flags/Description: MWAIT 0x20
Latency: 104
Usage: 53268
Duration: 229366052
C7-SNB:
Flags/Description: MWAIT 0x30
Latency: 109
Usage: 62593595
Duration: 324631233978

After finding out which processor idle states are supported with cpupower idle-info, individual states can be disabled using the cpupower idle-set command. Typically one wants to disable the deepest sleep state, for example:

cpupower idle-set -d 5

Or, for disabling all CPUs with latencies equal to or higher than 80:

cpupower idle-set -D 80

11.3.3 Monitoring Kernel and Hardware Statistics with cpupower

Use the monitor subcommand to report processor topology, and monitor frequency and idle power state statistics over a certain period of time. The default interval is 1 second, but it can be changed with the -i. Independent processor sleep states and frequency counters are implemented in the tool—some retrieved from kernel statistics, others reading out hardware registers. The available monitors depend on the underlying hardware and the system. List them with cpupower monitor -l. For a description of the individual monitors, refer to the cpupower-monitor man page.

The monitor subcommand allows you to execute performance benchmarks. To compare kernel statistics with hardware statistics for specific workloads, concatenate the respective command, for example:

cpupower monitor db_test.sh
Example 11.3: Example cpupower monitor Output
root # cpupower monitor
|Mperf                   || Idle_Stats
 1                         2 
CPU | C0   | Cx   | Freq || POLL | C1   | C2   | C3
   0|  3.71| 96.29|  2833||  0.00|  0.00|  0.02| 96.32
   1| 100.0| -0.00|  2833||  0.00|  0.00|  0.00|  0.00
   2|  9.06| 90.94|  1983||  0.00|  7.69|  6.98| 76.45
   3|  7.43| 92.57|  2039||  0.00|  2.60| 12.62| 77.52

1

Mperf shows the average frequency of a CPU, including boost frequencies, over time. Additionally, it shows the percentage of time the CPU has been active (C0) or in any sleep state (Cx). As the turbo states are managed by the BIOS, it is impossible to get the frequency values at a given instant. On modern processors with turbo features the Mperf monitor is the only way to find out about the frequency a certain CPU has been running in.

2

Idle_Stats shows the statistics of the cpuidle kernel subsystem. The kernel updates these values every time an idle state is entered or left. Therefore there can be some inaccuracy when cores are in an idle state for some time when the measure starts or ends.

Apart from the (general) monitors in the example above, other architecture-specific monitors are available. For detailed information, refer to the cpupower-monitor man page.

By comparing the values of the individual monitors, you can find correlations and dependencies and evaluate how well the power saving mechanism works for a certain workload. In Example 11.3 you can see that CPU 0 is idle (the value of Cx is near 100%), but runs at a very high frequency. This is because the CPUs 0 and 1 have the same frequency values which means that there is a dependency between them.

11.3.4 Modifying Current Settings with cpupower

You can use cpupower frequency-set command as root to modify current settings. It allows you to set values for the minimum or maximum CPU frequency the governor may select or to create a new governor. With the -c option, you can also specify for which of the processors the settings should be modified. That makes it easy to use a consistent policy across all processors without adjusting the settings for each processor individually. For more details and the available options, refer to the cpupower-freqency-set man page or run cpupower frequency-set --help.

11.4 Special Tuning Options

The following sections highlight important settings.

11.4.1 Tuning Options for P-States

The CPUfreq subsystem offers several tuning options for P-states: You can switch between the different governors, influence minimum or maximum CPU frequency to be used or change individual governor parameters.

To switch to another governor at runtime, use cpupower frequency-set with the -g option. For example, running the following command (as root) will activate the performance governor:

cpupower frequency-set -g performance

To set values for the minimum or maximum CPU frequency the governor may select, use the -d or -u option, respectively.

11.5 Troubleshooting

BIOS options enabled?

To use C-states or P-states, check your BIOS options:

  • To use C-states, make sure to enable CPU C State or similar options to benefit from power savings at idle.

  • To use P-states and the CPUfreq governors, make sure to enable Processor Performance States options or similar.

  • Even if P-states and C-states are available, it is possible that the platform firmware is managing CPU frequencies which may be sub-optimal. For example, if pcc-cpufreq is loaded then the OS is only giving hints to the firmware, which is free to ignore the hints. This can be addressed by selecting "OS Management" or similar for CPU frequency managed in the BIOS. After reboot, an alternative driver will be used but the performance impact should be carefully measured.

In case of a CPU upgrade, make sure to upgrade your BIOS, too. The BIOS needs to know the new CPU and its frequency stepping to pass this information on to the operating system.

Log file information?

Check the systemd journal (see Chapter 15, journalctl: Query the systemd Journal) for any output regarding the CPUfreq subsystem. Only severe errors are reported there.

If you suspect problems with the CPUfreq subsystem on your machine, you can also enable additional debug output. To do so, either use cpufreq.debug=7 as boot parameter or execute the following command as root:

echo 7 > /sys/module/cpufreq/parameters/debug

This will cause CPUfreq to log more information to dmesg on state transitions, which is useful for diagnosis. But as this additional output of kernel messages can be rather comprehensive, use it only if you are fairly sure that a problem exists.

11.6 For More Information

Platforms with a Baseboard Management Controller (BMC) may have additional power management configuration options accessible via the service processor. These configurations are vendor specific and therefore not subject of this guide. For more information, refer to the manuals provided by your vendor.

Part V Kernel Tuning

12 Tuning I/O Performance

I/O scheduling controls how input/output operations will be submitted to storage. SUSE Linux Enterprise Server offers various I/O algorithms—called elevators—suiting different workloads. Elevators can help to reduce seek operations and can prioritize I/O requests.

13 Tuning the Task Scheduler

Modern operating systems, such as SUSE® Linux Enterprise Server, normally run many tasks at the same time. For example, you can be searching in a text file while receiving an e-mail and copying a big file to an external hard disk. These simple tasks require many additional processes to be run by the…

14 Tuning the Memory Management Subsystem

To understand and tune the memory management behavior of the kernel, it is important to first have an overview of how it works and cooperates with other subsystems.

15 Tuning the Network

The network subsystem is complex and its tuning highly depends on the system use scenario and on external factors such as software clients or hardware components (switches, routers, or gateways) in your network. The Linux kernel aims more at reliability and low latency than low overhead and high thr…

12 Tuning I/O Performance

  • Filename: tuning_storagescheduler.xml
  • ID: cha.tuning.io

I/O scheduling controls how input/output operations will be submitted to storage. SUSE Linux Enterprise Server offers various I/O algorithms—called elevators—suiting different workloads. Elevators can help to reduce seek operations and can prioritize I/O requests.

Choosing the best suited I/O elevator not only depends on the workload, but on the hardware, too. Single ATA disk systems, SSDs, RAID arrays, or network storage systems, for example, each require different tuning strategies.

12.1 Switching I/O Scheduling

SUSE Linux Enterprise Server picks a default I/O scheduler at boot-time, which can be changed on the fly per block device. This makes it possible to set different algorithms, for example, for the device hosting the system partition and the device hosting a database.

The default I/O scheduler is chosen for each device based on whether the device reports to be rotational disk or not. For non-rotational disks DEADLINE I/O scheduler is picked. Other devices default to CFQ (Completely Fair Queuing). To change this default, use the following boot parameter:

elevator=SCHEDULER

Replace SCHEDULER with one of the values cfq, noop, or deadline. See Section 12.2, “Available I/O Elevators” for details.

To change the elevator for a specific device in the running system, run the following command:

echo SCHEDULER > /sys/block/DEVICE/queue/scheduler

Here, SCHEDULER is one of cfq, noop, or deadline. DEVICE is the block device (sda for example). Note that this change will not persist during reboot. For permanent I/O scheduler change for a particular device either place the command switching the I/O scheduler into init scripts or add appropriate udev rule into /lib/udev/rules.d/. See /lib/udev/rules.d/60-ssd-scheduler.rules for an example of such tuning.

Note
Note: Default Scheduler on IBM z Systems

On IBM z Systems, the default I/O scheduler for a storage device is set by the device driver.

12.2 Available I/O Elevators

In the following elevators available on SUSE Linux Enterprise Server are listed. Each elevator has a set of tunable parameters, which can be set with the following command:

echo VALUE > /sys/block/DEVICE/queue/iosched/TUNABLE

where VALUE is the desired value for the TUNABLE and DEVICE the block device.

To find out which elevator is the current default, run the following command. The currently selected scheduler is listed in brackets:

jupiter:~ # cat /sys/block/sda/queue/scheduler
noop deadline [cfq]

This file can also contain the string none meaning that I/O scheduling does not happen for this device. This is usually because the device uses multi-queue queueing mechanism (refer to Section 12.4, “Enable blk-mq I/O Path for SCSI by Default”).

12.2.1 CFQ (Completely Fair Queuing)

CFQ is a fairness-oriented scheduler and is used by default on SUSE Linux Enterprise Server. The algorithm assigns each thread a time slice in which it is allowed to submit I/O to disk. This way each thread gets a fair share of I/O throughput. It also allows assigning tasks I/O priorities which are taken into account during scheduling decisions (see Section 8.3.3, “Prioritizing Disk Access with ionice). The CFQ scheduler has the following tunable parameters:

/sys/block/DEVICE/queue/iosched/slice_idle_us

When a task has no more I/O to submit in its time slice, the I/O scheduler waits for a while before scheduling the next thread. The slice_idle_us is the time in microseconds the I/O scheduler waits. File slice_idle controls the same tunable but in millisecond units. Waiting for more I/O from a thread can improve locality of I/O. Additionally, it avoids starving processes doing dependent I/O. A process does dependent I/O if it needs a result of one I/O to submit another I/O. For example, if you first need to read an index block to find out a data block to read, these two reads form a dependent I/O.

For media where locality does not play a big role (SSDs, SANs with lots of disks) setting /sys/block/<device>/queue/iosched/slice_idle_us to 0 can improve the throughput considerably.

/sys/block/DEVICE/queue/iosched/quantum

This option limits the maximum number of requests that are being processed at once by the device. The default value is 4. For a storage with several disks, this setting can unnecessarily limit parallel processing of requests. Therefore, increasing the value can improve performance. However, it can also cause latency of certain I/O operations to increase because more requests are buffered inside the storage. When changing this value, you can also consider tuning /sys/block/DEVICE/queue/iosched/slice_async_rq (the default value is 2). This limits the maximum number of asynchronous requests—usually write requests—that are submitted in one time slice.

/sys/block/DEVICE/queue/iosched/low_latency

When enabled (which is the default on SUSE Linux Enterprise Server) the scheduler may dynamically adjust the length of the time slice by aiming to meet a tuning parameter called the target_latency. Time slices are recomputed to meet this target_latency and ensure that processes get fair access within a bounded length of time.

/sys/block/DEVICE/queue/iosched/target_latency

Contains an estimated latency time for the CFQ. CFQ will use it to calculate the time slice used for every task.

/sys/block/DEVICE/queue/iosched/group_idle_us

To avoid starving of blkio cgroups doing dependent I/O, CFQ waits a bit after completion of I/O for one blkio cgroup before scheduling I/O for a different blkio cgroup. When slice_idle_us is set, this parameter does not have a big impact. However, for fast media, the overhead of slice_idle_us is generally undesirable. Disabling slice_idle_us and setting group_idle_us is a method to avoid starvation of blkio cgroups doing dependent I/O with lower overhead. Note that the file group_idle controls the same tunable however with millisecond granularity.

Example 12.1: Increasing individual thread throughput using CFQ

In SUSE Linux Enterprise Server 12 SP3, the low_latency tuning parameter is enabled by default to ensure that processes get fair access within a bounded length of time. (Note that this parameter was not enabled in versions prior to SUSE Linux Enterprise 12.)

This is usually preferred in a server scenario where processes are executing I/O as part of transactions, as it makes the time needed for each transaction predictable. However, there are scenarios where that is not the desired behavior:

  • If the performance metric of interest is the peak performance of a single process when there is I/O contention.

  • If a workload must complete as quickly as possible and there are multiple sources of I/O. In this case, unfair treatment from the I/O scheduler may allow the transactions to complete faster: Processes take their full slice and exit quickly, resulting in reduced overall contention.

To address this, there are two options—increase target_latency or disable low_latency. As with all tuning parameters it is important to verify your workload behaves as expected before and after the tuning modification. Take careful note of whether your workload depends on individual process peak performance or scales better with fairness. It should also be noted that the performance will depend on the underlying storage and the correct tuning option for one installation may not be universally true.

Find below an example that does not control when I/O starts but is simple enough to demonstrate the point. 32 processes are writing a small amount of data to disk in parallel. Using the SUSE Linux Enterprise Server default (enabling low_latency), the result looks as follows:

root # echo 1 > /sys/block/sda/queue/iosched/low_latency
root # time ./dd-test.sh
10485760 bytes (10 MB) copied, 2.62464 s, 4.0 MB/s
10485760 bytes (10 MB) copied, 3.29624 s, 3.2 MB/s
10485760 bytes (10 MB) copied, 3.56341 s, 2.9 MB/s
10485760 bytes (10 MB) copied, 3.56908 s, 2.9 MB/s
10485760 bytes (10 MB) copied, 3.53043 s, 3.0 MB/s
10485760 bytes (10 MB) copied, 3.57511 s, 2.9 MB/s
10485760 bytes (10 MB) copied, 3.53672 s, 3.0 MB/s
10485760 bytes (10 MB) copied, 3.5433 s, 3.0 MB/s
10485760 bytes (10 MB) copied, 3.65474 s, 2.9 MB/s
10485760 bytes (10 MB) copied, 3.63694 s, 2.9 MB/s
10485760 bytes (10 MB) copied, 3.90122 s, 2.7 MB/s
10485760 bytes (10 MB) copied, 3.88507 s, 2.7 MB/s
10485760 bytes (10 MB) copied, 3.86135 s, 2.7 MB/s
10485760 bytes (10 MB) copied, 3.84553 s, 2.7 MB/s
10485760 bytes (10 MB) copied, 3.88871 s, 2.7 MB/s
10485760 bytes (10 MB) copied, 3.94943 s, 2.7 MB/s
10485760 bytes (10 MB) copied, 4.12731 s, 2.5 MB/s
10485760 bytes (10 MB) copied, 4.15106 s, 2.5 MB/s
10485760 bytes (10 MB) copied, 4.21601 s, 2.5 MB/s
10485760 bytes (10 MB) copied, 4.35004 s, 2.4 MB/s
10485760 bytes (10 MB) copied, 4.33387 s, 2.4 MB/s
10485760 bytes (10 MB) copied, 4.55434 s, 2.3 MB/s
10485760 bytes (10 MB) copied, 4.52283 s, 2.3 MB/s
10485760 bytes (10 MB) copied, 4.52682 s, 2.3 MB/s
10485760 bytes (10 MB) copied, 4.56176 s, 2.3 MB/s
10485760 bytes (10 MB) copied, 4.62727 s, 2.3 MB/s
10485760 bytes (10 MB) copied, 4.78958 s, 2.2 MB/s
10485760 bytes (10 MB) copied, 4.79772 s, 2.2 MB/s
10485760 bytes (10 MB) copied, 4.78004 s, 2.2 MB/s
10485760 bytes (10 MB) copied, 4.77994 s, 2.2 MB/s
10485760 bytes (10 MB) copied, 4.86114 s, 2.2 MB/s
10485760 bytes (10 MB) copied, 4.88062 s, 2.1 MB/s

real    0m4.978s
user    0m0.112s
sys     0m1.544s

Note that each process completes in similar times. This is the CFQ scheduler meeting its target_latency: Each process has fair access to storage.

Note that the earlier processes complete somewhat faster. This happens because the start time of the processes is not identical. In a more complicated example, it is possible to control for this.

This is what happens when low_latency is disabled:

root # echo 0 > /sys/block/sda/queue/iosched/low_latency
root # time ./dd-test.sh
10485760 bytes (10 MB) copied, 0.813519 s, 12.9 MB/s
10485760 bytes (10 MB) copied, 0.788106 s, 13.3 MB/s
10485760 bytes (10 MB) copied, 0.800404 s, 13.1 MB/s
10485760 bytes (10 MB) copied, 0.816398 s, 12.8 MB/s
10485760 bytes (10 MB) copied, 0.959087 s, 10.9 MB/s
10485760 bytes (10 MB) copied, 1.09563 s, 9.6 MB/s
10485760 bytes (10 MB) copied, 1.18716 s, 8.8 MB/s
10485760 bytes (10 MB) copied, 1.27661 s, 8.2 MB/s
10485760 bytes (10 MB) copied, 1.46312 s, 7.2 MB/s
10485760 bytes (10 MB) copied, 1.55489 s, 6.7 MB/s
10485760 bytes (10 MB) copied, 1.64277 s, 6.4 MB/s
10485760 bytes (10 MB) copied, 1.78196 s, 5.9 MB/s
10485760 bytes (10 MB) copied, 1.87496 s, 5.6 MB/s
10485760 bytes (10 MB) copied, 1.9461 s, 5.4 MB/s
10485760 bytes (10 MB) copied, 2.08351 s, 5.0 MB/s
10485760 bytes (10 MB) copied, 2.28003 s, 4.6 MB/s
10485760 bytes (10 MB) copied, 2.42979 s, 4.3 MB/s
10485760 bytes (10 MB) copied, 2.54564 s, 4.1 MB/s
10485760 bytes (10 MB) copied, 2.6411 s, 4.0 MB/s
10485760 bytes (10 MB) copied, 2.75171 s, 3.8 MB/s
10485760 bytes (10 MB) copied, 2.86162 s, 3.7 MB/s
10485760 bytes (10 MB) copied, 2.98453 s, 3.5 MB/s
10485760 bytes (10 MB) copied, 3.13723 s, 3.3 MB/s
10485760 bytes (10 MB) copied, 3.36399 s, 3.1 MB/s
10485760 bytes (10 MB) copied, 3.60018 s, 2.9 MB/s
10485760 bytes (10 MB) copied, 3.58151 s, 2.9 MB/s
10485760 bytes (10 MB) copied, 3.67385 s, 2.9 MB/s
10485760 bytes (10 MB) copied, 3.69471 s, 2.8 MB/s
10485760 bytes (10 MB) copied, 3.66658 s, 2.9 MB/s
10485760 bytes (10 MB) copied, 3.81495 s, 2.7 MB/s
10485760 bytes (10 MB) copied, 4.10172 s, 2.6 MB/s
10485760 bytes (10 MB) copied, 4.0966 s, 2.6 MB/s

real    0m3.505s
user    0m0.160s
sys     0m1.516s

Note that the time processes take to complete is spread much wider as processes are not getting fair access. Some processes complete faster and exit, allowing the total workload to complete faster, and some processes measure higher apparent I/O performance. It is also important to note that this example may not behave similarly on all systems as the results depend on the resources of the machine and the underlying storage.

It is important to emphasize that neither tuning option is inherently better than the other. Both are best in different circumstances and it is important to understand the requirements of your workload and tune accordingly.

12.2.2 NOOP

A trivial scheduler that only passes down the I/O that comes to it. Useful for checking whether complex I/O scheduling decisions of other schedulers are causing I/O performance regressions.

This scheduler is recommended for setups with devices that do I/O scheduling themselves, such as intelligent storage or in multipathing environments. If you choose a more complicated scheduler on the host, the scheduler of the host and the scheduler of the storage device compete with each other. This can decrease performance. The storage device can usually determine best how to schedule I/O.

For similar reasons, this scheduler is also recommended for use within virtual machines.

The NOOP scheduler can be useful for devices that do not depend on mechanical movement, like SSDs. Usually, the DEADLINE I/O scheduler is a better choice for these devices. However, NOOP creates less overhead and thus can on certain workloads increase performance.

12.2.3 DEADLINE

DEADLINE is a latency-oriented I/O scheduler. Each I/O request is assigned a deadline. Usually, requests are stored in queues (read and write) sorted by sector numbers. The DEADLINE algorithm maintains two additional queues (read and write) in which requests are sorted by deadline. As long as no request has timed out, the sector queue is used. When timeouts occur, requests from the deadline queue are served until there are no more expired requests. Generally, the algorithm prefers reads over writes.

This scheduler can provide a superior throughput over the CFQ I/O scheduler in cases where several threads read and write and fairness is not an issue. For example, for several parallel readers from a SAN and for databases (especially when using TCQ disks). The DEADLINE scheduler has the following tunable parameters:

/sys/block/<device>/queue/iosched/writes_starved

Controls how many reads can be sent to disk before it is possible to send writes. A value of 3 means, that three read operations are carried out for one write operation.

/sys/block/<device>/queue/iosched/read_expire

Sets the deadline (current time plus the read_expire value) for read operations in milliseconds. The default is 500.

/sys/block/<device>/queue/iosched/write_expire

/sys/block/<device>/queue/iosched/read_expire Sets the deadline (current time plus the read_expire value) for read operations in milliseconds. The default is 500.

12.3 I/O Barrier Tuning

Most file systems (such as XFS, Ext3, Ext4, or reiserfs) send write barriers to disk after fsync or during transaction commits. Write barriers enforce proper ordering of writes, making volatile disk write caches safe to use (at some performance penalty). If your disks are battery-backed in one way or another, disabling barriers can safely improve performance.

Sending write barriers can be disabled using the nobarrier mount option.

Warning
Warning: Disabling Barriers Can Lead to Data Loss

Disabling barriers when disks cannot guarantee caches are properly written in case of power failure can lead to severe file system corruption and data loss.

12.4 Enable blk-mq I/O Path for SCSI by Default

Block multiqueue (blk-mq) is a multi-queue block I/O queueing mechanism. Blk-mq uses per-cpu software queues to queue I/O requests. The software queues are mapped to one or more hardware submission queues. Blk-mq significantly reduces lock contention. In particular blk-mq improves performance for devices that support a high number of input/output operations per second (IOPS). Blk-mq is already the default for some devices, for example, NVM Express devices.

Currently blk-mq has no I/O scheduling support (no CFQ, no deadline I/O scheduler). This lack of I/O scheduling can cause significant performance degradation when spinning disks are used. Therefore blk-mq is not enabled by default for SCSI devices.

If you have fast SCSI devices (for example, SSDs) instead of SCSI hard disks attached to your system, consider switching to blk-mq for SCSI. This is done using the kernel command line option scsi_mod.use_blk_mq=1.

13 Tuning the Task Scheduler

  • Filename: tuning_taskscheduler.xml
  • ID: cha.tuning.taskscheduler

Modern operating systems, such as SUSE® Linux Enterprise Server, normally run many tasks at the same time. For example, you can be searching in a text file while receiving an e-mail and copying a big file to an external hard disk. These simple tasks require many additional processes to be run by the system. To provide each task with its required system resources, the Linux kernel needs a tool to distribute available system resources to individual tasks. And this is exactly what the task scheduler does.

The following sections explain the most important terms related to a process scheduling. They also introduce information about the task scheduler policy, scheduling algorithm, description of the task scheduler used by SUSE Linux Enterprise Server, and references to other sources of relevant information.

13.1 Introduction

The Linux kernel controls the way that tasks (or processes) are managed on the system. The task scheduler, sometimes called process scheduler, is the part of the kernel that decides which task to run next. It is responsible for best using system resources to guarantee that multiple tasks are being executed simultaneously. This makes it a core component of any multitasking operating system.

13.1.1 Preemption

The theory behind task scheduling is very simple. If there are runnable processes in a system, at least one process must always be running. If there are more runnable processes than processors in a system, not all the processes can be running all the time.

Therefore, some processes need to be stopped temporarily, or suspended, so that others can be running again. The scheduler decides what process in the queue will run next.

As already mentioned, Linux, like all other Unix variants, is a multitasking operating system. That means that several tasks can be running at the same time. Linux provides a so called preemptive multitasking, where the scheduler decides when a process is suspended. This forced suspension is called preemption. All Unix flavors have been providing preemptive multitasking since the beginning.

13.1.2 Timeslice

The time period for which a process will be running before it is preempted is defined in advance. It is called a timeslice of a process and represents the amount of processor time that is provided to each process. By assigning timeslices, the scheduler makes global decisions for the running system, and prevents individual processes from dominating over the processor resources.

13.1.3 Process Priority

The scheduler evaluates processes based on their priority. To calculate the current priority of a process, the task scheduler uses complex algorithms. As a result, each process is given a value according to which it is allowed to run on a processor.

13.2 Process Classification

Processes are usually classified according to their purpose and behavior. Although the borderline is not always clearly distinct, generally two criteria are used to sort them. These criteria are independent and do not exclude each other.

One approach is to classify a process either I/O-bound or processor-bound.

I/O-bound

I/O stands for Input/Output devices, such as keyboards, mice, or optical and hard disks. I/O-bound processes spend the majority of time submitting and waiting for requests. They are run very frequently, but for short time intervals, not to block other processes waiting for I/O requests.

processor-bound

On the other hand, processor-bound tasks use their time to execute a code, and usually run until they are preempted by the scheduler. They do not block processes waiting for I/O requests, and, therefore, can be run less frequently but for longer time intervals.

Another approach is to divide processes by type into interactive, batch, and real-time processes.

  • Interactive processes spend a lot of time waiting for I/O requests, such as keyboard or mouse operations. The scheduler must wake up such processes quickly on user request, or the user will find the environment unresponsive. The typical delay is approximately 100 ms. Office applications, text editors or image manipulation programs represent typical interactive processes.

  • Batch processes often run in the background and do not need to be responsive. They usually receive lower priority from the scheduler. Multimedia converters, database search engines, or log files analyzers are typical examples of batch processes.

  • Real-time processes must never be blocked by low-priority processes, and the scheduler guarantees a short response time to them. Applications for editing multimedia content are a good example here.

13.3 Completely Fair Scheduler

Since the Linux kernel version 2.6.23, a new approach has been taken to the scheduling of runnable processes. Completely Fair Scheduler (CFS) became the default Linux kernel scheduler. Since then, important changes and improvements have been made. The information in this chapter applies to SUSE Linux Enterprise Server with kernel version 2.6.32 and higher (including 3.x kernels). The scheduler environment was divided into several parts, and three main new features were introduced:

Modular Scheduler Core

The core of the scheduler was enhanced with scheduling classes. These classes are modular and represent scheduling policies.

Completely Fair Scheduler

Introduced in kernel 2.6.23 and extended in 2.6.24, CFS tries to assure that each process obtains its fair share of the processor time.

Group Scheduling

For example, if you split processes into groups according to which user is running them, CFS tries to provide each of these groups with the same amount of processor time.

As a result, CFS brings optimized scheduling for both servers and desktops.

13.3.1 How CFS Works

CFS tries to guarantee a fair approach to each runnable task. To find the most balanced way of task scheduling, it uses the concept of red-black tree. A red-black tree is a type of self-balancing data search tree which provides inserting and removing entries in a reasonable way so that it remains well balanced. For more information, see the wiki pages of Red-black tree.

When CFS schedules a task it accumulates virtual runtime or vruntime. The next task picked to run is always the task with the minimum accumulated vruntime so far. By balancing the red-black tree when tasks are inserted into the run queue (a planned time line of processes to be executed next), the task with the minimum vruntime is always the first entry in the red-black tree.

The amount of vruntime a task accrues is related to its priority. High priority tasks gain vruntime at a slower rate than low priority tasks, which results in high priority tasks being picked to run on the processor more often.

13.3.2 Grouping Processes

Since the Linux kernel version 2.6.24, CFS can be tuned to be fair to groups rather than to tasks only. Runnable tasks are then grouped to form entities, and CFS tries to be fair to these entities instead of individual runnable tasks. The scheduler also tries to be fair to individual tasks within these entities.

The kernel scheduler lets you group runnable tasks using control groups. For more information, see Chapter 9, Kernel Control Groups.

13.3.3 Kernel Configuration Options

Basic aspects of the task scheduler behavior can be set through the kernel configuration options. Setting these options is part of the kernel compilation process. Because kernel compilation process is a complex task and out of this document's scope, refer to relevant source of information.

Warning
Warning: Kernel Compilation

If you run SUSE Linux Enterprise Server on a kernel that was not shipped with it, for example on a self-compiled kernel, you lose the entire support entitlement.

13.3.4 Terminology

Documents regarding task scheduling policy often use several technical terms which you need to know to understand the information correctly. Here are some:

Latency

Delay between the time a process is scheduled to run and the actual process execution.

Granularity

The relation between granularity and latency can be expressed by the following equation:

gran = ( lat / rtasks ) - ( lat / rtasks / rtasks )

where gran stands for granularity, lat stand for latency, and rtasks is the number of running tasks.

13.3.4.1 Scheduling Policies

The Linux kernel supports the following scheduling policies:

SCHED_FIFO

Scheduling policy designed for special time-critical applications. It uses the First In-First Out scheduling algorithm.

SCHED_BATCH

Scheduling policy designed for CPU-intensive tasks.

SCHED_IDLE

Scheduling policy intended for very low prioritized tasks.

SCHED_OTHER

Default Linux time-sharing scheduling policy used by the majority of processes.

SCHED_RR

Similar to SCHED_FIFO, but uses the Round Robin scheduling algorithm.

13.3.5 Changing Real-time Attributes of Processes with chrt

The chrt command sets or retrieves the real-time scheduling attributes of a running process, or runs a command with the specified attributes. You can get or retrieve both the scheduling policy and priority of a process.

In the following examples, a process whose PID is 16244 is used.

To retrieve the real-time attributes of an existing task:

root # chrt -p 16244
pid 16244's current scheduling policy: SCHED_OTHER
pid 16244's current scheduling priority: 0

Before setting a new scheduling policy on the process, you need to find out the minimum and maximum valid priorities for each scheduling algorithm:

root # chrt -m
SCHED_SCHED_OTHER min/max priority : 0/0
SCHED_SCHED_FIFO min/max priority : 1/99
SCHED_SCHED_RR min/max priority : 1/99
SCHED_SCHED_BATCH min/max priority : 0/0
SCHED_SCHED_IDLE min/max priority : 0/0

In the above example, SCHED_OTHER, SCHED_BATCH, SCHED_IDLE polices only allow for priority 0, while that of SCHED_FIFO and SCHED_RR can range from 1 to 99.

To set SCHED_BATCH scheduling policy:

root # chrt -b -p 0 16244
pid 16244's current scheduling policy: SCHED_BATCH
pid 16244's current scheduling priority: 0

For more information on chrt, see its man page (man 1 chrt).

13.3.6 Runtime Tuning with sysctl

The sysctl interface for examining and changing kernel parameters at runtime introduces important variables by means of which you can change the default behavior of the task scheduler. The syntax of the sysctl is simple, and all the following commands must be entered on the command line as root.

To read a value from a kernel variable, enter

sysctl VARIABLE

To assign a value, enter

sysctl VARIABLE=VALUE

To get a list of all scheduler related sysctl variables, enter

sysctl -A | grep "sched" | grep -v"domain"
root # sysctl -A | grep "sched" | grep -v "domain"
kernel.sched_cfs_bandwidth_slice_us = 5000
kernel.sched_child_runs_first = 0
kernel.sched_compat_yield = 0
kernel.sched_latency_ns = 24000000
kernel.sched_migration_cost_ns = 500000
kernel.sched_min_granularity_ns = 8000000
kernel.sched_nr_migrate = 32
kernel.sched_rr_timeslice_ms = 25
kernel.sched_rt_period_us = 1000000
kernel.sched_rt_runtime_us = 950000
kernel.sched_schedstats = 0
kernel.sched_shares_window_ns = 10000000
kernel.sched_time_avg_ms = 1000
kernel.sched_tunable_scaling = 1
kernel.sched_wakeup_granularity_ns = 10000000

Note that variables ending with _ns and _us accept values in nanoseconds and microseconds, respectively.

A list of the most important task scheduler sysctl tuning variables (located at /proc/sys/kernel/) with a short description follows:

sched_cfs_bandwidth_slice_us

When CFS bandwidth control is in use, this parameter controls the amount of run-time (bandwidth) transferred to a run queue from the task's control group bandwidth pool. Small values allow the global bandwidth to be shared in a fine-grained manner among tasks, larger values reduce transfer overhead. See https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt.

sched_child_runs_first

A freshly forked child runs before the parent continues execution. Setting this parameter to 1 is beneficial for an application in which the child performs an execution after fork. For example make -j<NO_CPUS> performs better when sched_child_runs_first is turned off. The default value is 0.

sched_compat_yield

Enables the aggressive CPU yielding behavior of the old O(1) scheduler by moving the relinquishing task to the end of the runnable queue (right-most position in the red-black tree). Applications that depend on the sched_yield(2) syscall behavior may see performance improvements by giving other processes a chance to run when there are highly contended resources (such as locks). On the other hand, given that this call occurs in context switching, misusing the call can hurt the workload. Only use it when you see a drop in performance. The default value is 0.

sched_migration_cost_ns

Amount of time after the last execution that a task is considered to be cache hot in migration decisions. A hot task is less likely to be migrated to another CPU, so increasing this variable reduces task migrations. The default value is 500000 (ns).

If the CPU idle time is higher than expected when there are runnable processes, try reducing this value. If tasks bounce between CPUs or nodes too often, try increasing it.

sched_latency_ns

Targeted preemption latency for CPU bound tasks. Increasing this variable increases a CPU bound task's timeslice. A task's timeslice is its weighted fair share of the scheduling period:

timeslice = scheduling period * (task's weight/total weight of tasks in the run queue)

The task's weight depends on the task's nice level and the scheduling policy. Minimum task weight for a SCHED_OTHER task is 15, corresponding to nice 19. The maximum task weight is 88761, corresponding to nice -20.

Timeslices become smaller as the load increases. When the number of runnable tasks exceeds sched_latency_ns/sched_min_granularity_ns, the slice becomes number_of_running_tasks * sched_min_granularity_ns. Prior to that, the slice is equal to sched_latency_ns.

This value also specifies the maximum amount of time during which a sleeping task is considered to be running for entitlement calculations. Increasing this variable increases the amount of time a waking task may consume before being preempted, thus increasing scheduler latency for CPU bound tasks. The default value is 6000000 (ns).

sched_min_granularity_ns

Minimal preemption granularity for CPU bound tasks. See sched_latency_ns for details. The default value is 4000000 (ns).

sched_wakeup_granularity_ns

The wake-up preemption granularity. Increasing this variable reduces wake-up preemption, reducing disturbance of compute bound tasks. Lowering it improves wake-up latency and throughput for latency critical tasks, particularly when a short duty cycle load component must compete with CPU bound components. The default value is 2500000 (ns).

Warning
Warning: Setting the Right Wake-up Granularity Value

Settings larger than half of sched_latency_ns will result in no wake-up preemption. Short duty cycle tasks will be unable to compete with CPU hogs effectively.

sched_rr_timeslice_ms

Quantum that SCHED_RR tasks are allowed to run before they are preempted and put to the end of the task list.

sched_rt_period_us

Period over which real-time task bandwidth enforcement is measured. The default value is 1000000 (µs).

sched_rt_runtime_us

Quantum allocated to real-time tasks during sched_rt_period_us. Setting to -1 disables RT bandwidth enforcement. By default, RT tasks may consume 95%CPU/sec, thus leaving 5%CPU/sec or 0.05s to be used by SCHED_OTHER tasks. The default value is 950000 (µs).

sched_nr_migrate

Controls how many tasks can be migrated across processors for load-balancing purposes. Because balancing iterates the runqueue with interrupts disabled (softirq), it can incur in irq-latency penalties for real-time tasks. Therefore increasing this value may give a performance boost to large SCHED_OTHER threads at the expense of increased irq-latencies for real-time tasks. The default value is 32.

sched_time_avg_ms

This parameter sets the period over which the time spent running real-time tasks is averaged. That average assists CFS in making load-balancing decisions and gives an indication of how busy a CPU is with high-priority real-time tasks.

The optimal setting for this parameter is highly workload dependent and depends, among other things, on how frequently real-time tasks are running and for how long.

13.3.7 Debugging Interface and Scheduler Statistics

CFS comes with a new improved debugging interface, and provides runtime statistics information. Relevant files were added to the /proc file system, which can be examined simply with the cat or less command. A list of the related /proc files follows with their short description:

/proc/sched_debug

Contains the current values of all tunable variables (see Section 13.3.6, “Runtime Tuning with sysctl) that affect the task scheduler behavior, CFS statistics, and information about the run queues (CFS, RT and deadline) on all available processors. A summary of the task running on each processor is also shown, with the task name and PID, along with scheduler specific statistics. The first being tree-key column, it indicates the task's virtual runtime, and its name comes from the kernel sorting all runnable tasks by this key in a red-black tree. The switches column indicates the total number of switches (involuntary or not), and naturally the prio refers to the process priority. The wait-time value indicates the amount of time the task waited to be scheduled. Finally both sum-exec and sum-sleep account for the total amount of time (in nanoseconds) the task was running on the processor or asleep, respectively.

root # cat /proc/sched_debug
Sched Debug Version: v0.11, 4.4.21-64-default #1
ktime                                   : 23533900.395978
sched_clk                               : 23543587.726648
cpu_clk                                 : 23533900.396165
jiffies                                 : 4300775771
sched_clock_stable                      : 0

sysctl_sched
  .sysctl_sched_latency                    : 6.000000
  .sysctl_sched_min_granularity            : 2.000000
  .sysctl_sched_wakeup_granularity         : 2.500000
  .sysctl_sched_child_runs_first           : 0
  .sysctl_sched_features                   : 154871
  .sysctl_sched_tunable_scaling            : 1 (logaritmic)

cpu#0, 2666.762 MHz
  .nr_running                    : 1
  .load                          : 1024
  .nr_switches                   : 1918946
[...]

cfs_rq[0]:/
  .exec_clock                    : 170176.383770
  .MIN_vruntime                  : 0.000001
  .min_vruntime                  : 347375.854324
  .max_vruntime                  : 0.000001
[...]

rt_rq[0]:/
  .rt_nr_running                 : 0
  .rt_throttled                  : 0
  .rt_time                       : 0.000000
  .rt_runtime                    : 950.000000

dl_rq[0]:
  .dl_nr_running                 : 0

  task   PID         tree-key  switches  prio     wait-time        [...]
------------------------------------------------------------------------
R  cc1 63477     98876.717832       197   120      0.000000         ...
/proc/schedstat

Displays statistics relevant to the current run queue. Also domain-specific statistics for SMP systems are displayed for all connected processors. Because the output format is not user-friendly, read the contents of /usr/src/linux/Documentation/scheduler/sched-stats.txt for more information.

/proc/PID/sched

Displays scheduling information on the process with id PID.

root # cat /proc/$(pidof gdm)/sched
gdm (744, #threads: 3)
-------------------------------------------------------------------
se.exec_start                                :          8888.758381
se.vruntime                                  :          6062.853815
se.sum_exec_runtime                          :             7.836043
se.statistics.wait_start                     :             0.000000
se.statistics.sleep_start                    :          8888.758381
se.statistics.block_start                    :             0.000000
se.statistics.sleep_max                      :          1965.987638
[...]
se.avg.decay_count                           :                 8477
policy                                       :                    0
prio                                         :                  120
clock-delta                                  :                  128
mm->numa_scan_seq                            :                    0
numa_migrations, 0
numa_faults_memory, 0, 0, 1, 0, -1
numa_faults_memory, 1, 0, 0, 0, -1

13.4 For More Information

To get a compact knowledge about Linux kernel task scheduling, you need to explore several information sources. Here are some:

  • For task scheduler System Calls description, see the relevant manual page (for example man 2 sched_setaffinity).

  • General information on scheduling is described in Scheduling wiki page.

  • A useful lecture on Linux scheduler policy and algorithm is available in http://www.inf.fu-berlin.de/lehre/SS01/OS/Lectures/Lecture08.pdf.

  • A good overview of Linux process scheduling is given in Linux Kernel Development by Robert Love (ISBN-10: 0-672-32512-8). See http://www.informit.com/articles/article.aspx?p=101760.

  • A very comprehensive overview of the Linux kernel internals is given in Understanding the Linux Kernel by Daniel P. Bovet and Marco Cesati (ISBN 978-0-596-00565-8).

  • Technical information about task scheduler is covered in files under /usr/src/linux/Documentation/scheduler.

14 Tuning the Memory Management Subsystem

  • Filename: tuning_memory.xml
  • ID: cha.tuning.memory

To understand and tune the memory management behavior of the kernel, it is important to first have an overview of how it works and cooperates with other subsystems.

The memory management subsystem, also called the virtual memory manager, will subsequently be called VM. The role of the VM is to manage the allocation of physical memory (RAM) for the entire kernel and user programs. It is also responsible for providing a virtual memory environment for user processes (managed via POSIX APIs with Linux extensions). Finally, the VM is responsible for freeing up RAM when there is a shortage, either by trimming caches or swapping out anonymous memory.

The most important thing to understand when examining and tuning VM is how its caches are managed. The basic goal of the VM's caches is to minimize the cost of I/O as generated by swapping and file system operations (including network file systems). This is achieved by avoiding I/O completely, or by submitting I/O in better patterns.

Free memory will be used and filled up by these caches as required. The more memory is available for caches and anonymous memory, the more effectively caches and swapping will operate. However, if a memory shortage is encountered, caches will be trimmed or memory will be swapped out.

For a particular workload, the first thing that can be done to improve performance is to increase memory and reduce the frequency that memory must be trimmed or swapped. The second thing is to change the way caches are managed by changing kernel parameters.

Finally, the workload itself should be examined and tuned as well. If an application is allowed to run more processes or threads, effectiveness of VM caches can be reduced, if each process is operating in its own area of the file system. Memory overheads are also increased. If applications allocate their own buffers or caches, larger caches will mean that less memory is available for VM caches. However, more processes and threads can mean more opportunity to overlap and pipeline I/O, and may take better advantage of multiple cores. Experimentation will be required for the best results.

14.1 Memory Usage

Memory allocations in general can be characterized as pinned (also known as unreclaimable), reclaimable or swappable.

14.1.1 Anonymous Memory

Anonymous memory tends to be program heap and stack memory (for example, >malloc()). It is reclaimable, except in special cases such as mlock or if there is no available swap space. Anonymous memory must be written to swap before it can be reclaimed. Swap I/O (both swapping in and swapping out pages) tends to be less efficient than pagecache I/O, because of allocation and access patterns.

14.1.2 Pagecache

A cache of file data. When a file is read from disk or network, the contents are stored in pagecache. No disk or network access is required, if the contents are up-to-date in pagecache. tmpfs and shared memory segments count toward pagecache.

When a file is written to, the new data is stored in pagecache before being written back to a disk or the network (making it a write-back cache). When a page has new data not written back yet, it is called dirty. Pages not classified as dirty are clean. Clean pagecache pages can be reclaimed if there is a memory shortage by simply freeing them. Dirty pages must first be made clean before being reclaimed.

14.1.3 Buffercache

This is a type of pagecache for block devices (for example, /dev/sda). A file system typically uses the buffercache when accessing its on-disk metadata structures such as inode tables, allocation bitmaps, and so forth. Buffercache can be reclaimed similarly to pagecache.

14.1.4 Buffer Heads

Buffer heads are small auxiliary structures that tend to be allocated upon pagecache access. They can generally be reclaimed easily when the pagecache or buffercache pages are clean.

14.1.5 Writeback

As applications write to files, the pagecache becomes dirty and the buffercache may become dirty. When the amount of dirty memory reaches a specified number of pages in bytes (vm.dirty_background_bytes), or when the amount of dirty memory reaches a specific ratio to total memory (vm.dirty_background_ratio), or when the pages have been dirty for longer than a specified amount of time (vm.dirty_expire_centisecs), the kernel begins writeback of pages starting with files that had the pages dirtied first. The background bytes and ratios are mutually exclusive and setting one will overwrite the other. Flusher threads perform writeback in the background and allow applications to continue running. If the I/O cannot keep up with applications dirtying pagecache, and dirty data reaches a critical setting (vm.dirty_bytes or vm.dirty_ratio), then applications begin to be throttled to prevent dirty data exceeding this threshold.

14.1.6 Readahead

The VM monitors file access patterns and may attempt to perform readahead. Readahead reads pages into the pagecache from the file system that have not been requested yet. It is done to allow fewer, larger I/O requests to be submitted (more efficient). And for I/O to be pipelined (I/O performed at the same time as the application is running).

14.1.7 VFS caches

14.1.7.1 Inode Cache

This is an in-memory cache of the inode structures for each file system. These contain attributes such as the file size, permissions and ownership, and pointers to the file data.

14.1.7.2 Directory Entry Cache

This is an in-memory cache of the directory entries in the system. These contain a name (the name of a file), the inode which it refers to, and children entries. This cache is used when traversing the directory structure and accessing a file by name.

14.2 Reducing Memory Usage

14.2.1 Reducing malloc (Anonymous) Usage

Applications running on SUSE Linux Enterprise Server 12 SP3 can allocate more memory compared to SUSE Linux Enterprise Server 10. This is because of glibc changing its default behavior while allocating user space memory. See http://www.gnu.org/s/libc/manual/html_node/Malloc-Tunable-Parameters.html for explanation of these parameters.

To restore a SUSE Linux Enterprise Server 10-like behavior, M_MMAP_THRESHOLD should be set to 128*1024. This can be done with mallopt() call from the application, or via setting MALLOC_MMAP_THRESHOLD environment variable before running the application.

14.2.2 Reducing Kernel Memory Overheads

Kernel memory that is reclaimable (caches, described above) will be trimmed automatically during memory shortages. Most other kernel memory cannot be easily reduced but is a property of the workload given to the kernel.

Reducing the requirements of the user space workload will reduce the kernel memory usage (fewer processes, fewer open files and sockets, etc.)

14.2.3 Memory Controller (Memory Cgroups)

If the memory cgroups feature is not needed, it can be switched off by passing cgroup_disable=memory on the kernel command line, reducing memory consumption of the kernel a bit. There is also a slight performance benefit as there is a small amount of accounting overhead when memory cgroups are available even if none are configured.

14.3 Virtual Memory Manager (VM) Tunable Parameters

When tuning the VM it should be understood that some changes will take time to affect the workload and take full effect. If the workload changes throughout the day, it may behave very differently at different times. A change that increases throughput under some conditions may decrease it under other conditions.

14.3.1 Reclaim Ratios

/proc/sys/vm/swappiness

This control is used to define how aggressively the kernel swaps out anonymous memory relative to pagecache and other caches. Increasing the value increases the amount of swapping. The default value is 60.

Swap I/O tends to be much less efficient than other I/O. However, some pagecache pages will be accessed much more frequently than less used anonymous memory. The right balance should be found here.

If swap activity is observed during slowdowns, it may be worth reducing this parameter. If there is a lot of I/O activity and the amount of pagecache in the system is rather small, or if there are large dormant applications running, increasing this value might improve performance.

Note that the more data is swapped out, the longer the system will take to swap data back in when it is needed.

/proc/sys/vm/vfs_cache_pressure

This variable controls the tendency of the kernel to reclaim the memory which is used for caching of VFS caches, versus pagecache and swap. Increasing this value increases the rate at which VFS caches are reclaimed.

It is difficult to know when this should be changed, other than by experimentation. The slabtop command (part of the package procps) shows top memory objects used by the kernel. The vfs caches are the "dentry" and the "*_inode_cache" objects. If these are consuming a large amount of memory in relation to pagecache, it may be worth trying to increase pressure. Could also help to reduce swapping. The default value is 100.

/proc/sys/vm/min_free_kbytes

This controls the amount of memory that is kept free for use by special reserves including atomic allocations (those which cannot wait for reclaim). This should not normally be lowered unless the system is being very carefully tuned for memory usage (normally useful for embedded rather than server applications). If page allocation failure messages and stack traces are frequently seen in logs, min_free_kbytes could be increased until the errors disappear. There is no need for concern, if these messages are very infrequent. The default value depends on the amount of RAM.

/proc/sys/vm/watermark_scale_factor

Broadly speaking, free memory has high, low and min watermarks. When the low watermark is reached then kswapd wakes to reclaim memory in the background. It stays awake until free memory reaches the high watermark. Applications will stall and reclaim memory when the low watermark is reached.

The watermark_scale_factor defines the amount of memory left in a node/system before kswapd is woken up and how much memory needs to be free before kswapd goes back to sleep. The unit is in fractions of 10,000. The default value of 10 means the distances between watermarks are 0.1% of the available memory in the node/system. The maximum value is 1000, or 10% of memory.

Workloads that frequently stall in direct reclaim, accounted by allocstall in /proc/vmstat, may benefit from altering this parameter. Similarly, if kswapd is sleeping prematurely, as accounted for by kswapd_low_wmark_hit_quickly, then it may indicate that the number of pages kept free to avoid stalls is too low.

14.3.2 Writeback Parameters

One important change in writeback behavior since SUSE Linux Enterprise Server 10 is that modification to file-backed mmap() memory is accounted immediately as dirty memory (and subject to writeback). Whereas previously it would only be subject to writeback after it was unmapped, upon an msync() system call, or under heavy memory pressure.

Some applications do not expect mmap modifications to be subject to such writeback behavior, and performance can be reduced. Berkeley DB (and applications using it) is one known example that can cause problems. Increasing writeback ratios and times can improve this type of slowdown.

/proc/sys/vm/dirty_background_ratio

This is the percentage of the total amount of free and reclaimable memory. When the amount of dirty pagecache exceeds this percentage, writeback threads start writing back dirty memory. The default value is 10 (%).

/proc/sys/vm/dirty_background_bytes

This contains the amount of dirty memory at which the background kernel flusher threads will start writeback. dirty_background_bytes is the counterpart of dirty_background_ratio. If one of them is set, the other one will automatically be read as 0.

/proc/sys/vm/dirty_ratio

Similar percentage value as for dirty_background_ratio. When this is exceeded, applications that want to write to the pagecache are blocked and wait for kernel background flusher threads to reduce the amount of dirty memory. The default value is 20 (%).

/proc/sys/vm/dirty_bytes

This file controls the same tunable as dirty_ratio however the amount of dirty memory is in bytes as opposed to a percentage of reclaimable memory. Since both dirty_ratio and dirty_bytes control the same tunable, if one of them is set, the other one will automatically be read as 0. The minimum value allowed for dirty_bytes is two pages (in bytes); any value lower than this limit will be ignored and the old configuration will be retained.

/proc/sys/vm/dirty_expire_centisecs

Data which has been dirty in-memory for longer than this interval will be written out next time a flusher thread wakes up. Expiration is measured based on the modification time of a file's inode. Therefore, multiple dirtied pages from the same file will all be written when the interval is exceeded.

dirty_background_ratio and dirty_ratio together determine the pagecache writeback behavior. If these values are increased, more dirty memory is kept in the system for a longer time. With more dirty memory allowed in the system, the chance to improve throughput by avoiding writeback I/O and to submitting more optimal I/O patterns increases. However, more dirty memory can either harm latency when memory needs to be reclaimed or at points of data integrity (synchronization points) when it needs to be written back to disk.

14.3.3 Timing Differences of I/O Writes between SUSE Linux Enterprise 12 and SUSE Linux Enterprise 11

The system is required to limit what percentage of the system's memory contains file-backed data that needs writing to disk. This guarantees that the system can always allocate the necessary data structures to complete I/O. The maximum amount of memory that can be dirty and requires writing at any time is controlled by vm.dirty_ratio (/proc/sys/vm/dirty_ratio). The defaults are:

SLE-11-SP3:     vm.dirty_ratio = 40
SLE-12:         vm.dirty_ratio = 20

The primary advantage of using the lower ratio in SUSE Linux Enterprise 12 is that page reclamation and allocation in low memory situations completes faster as there is a higher probability that old clean pages will be quickly found and discarded. The secondary advantage is that if all data on the system must be synchronized, then the time to complete the operation on SUSE Linux Enterprise 12 will be lower than SUSE Linux Enterprise 11 SP3 by default. Most workloads will not notice this change as data is synchronized with fsync() by the application or data is not dirtied quickly enough to hit the limits.

There are exceptions and if your application is affected by this, it will manifest as an unexpected stall during writes. To prove it is affected by dirty data rate limiting then monitor /proc/PID_OF_APPLICATION/stack and it will be observed that the application spends significant time in balance_dirty_pages_ratelimited. If this is observed and it is a problem, then increase the value of vm.dirty_ratio to 40 to restore the SUSE Linux Enterprise 11 SP3 behavior.

It is important to note that the overall I/O throughput is the same regardless of the setting. The only difference is the timing of when the I/O is queued.

This is an example of using dd to asynchronously write 30% of memory to disk which would happen to be affected by the change in vm.dirty_ratio:

root # MEMTOTAL_MBYTES=`free -m | grep Mem: | awk '{print $2}'`
root # sysctl vm.dirty_ratio=40
root # dd if=/dev/zero of=zerofile ibs=1048576 count=$((MEMTOTAL_MBYTES*30/100))
2507145216 bytes (2.5 GB) copied, 8.00153 s, 313 MB/s
root # sysctl vm.dirty_ratio=20
dd if=/dev/zero of=zerofile ibs=1048576 count=$((MEMTOTAL_MBYTES*30/100))
2507145216 bytes (2.5 GB) copied, 10.1593 s, 247 MB/s

Note that the parameter affects the time it takes for the command to complete and the apparent write speed of the device. With dirty_ratio=40, more of the data is cached and written to disk in the background by the kernel. It is very important to note that the speed of I/O is identical in both cases. To demonstrate, this is the result when dd synchronizes the data before exiting:

root # sysctl vm.dirty_ratio=40
root # dd if=/dev/zero of=zerofile ibs=1048576 count=$((MEMTOTAL_MBYTES*30/100)) conv=fdatasync
2507145216 bytes (2.5 GB) copied, 21.0663 s, 119 MB/s
root # sysctl vm.dirty_ratio=20
root # dd if=/dev/zero of=zerofile ibs=1048576 count=$((MEMTOTAL_MBYTES*30/100)) conv=fdatasync
2507145216 bytes (2.5 GB) copied, 21.7286 s, 115 MB/s

Note that dirty_ratio had almost no impact here and is within the natural variability of a command. Hence, dirty_ratio does not directly impact I/O performance but it may affect the apparent performance of a workload that writes data asynchronously without synchronizing.

14.3.4 Readahead Parameters

/sys/block/<bdev>/queue/read_ahead_kb

If one or more processes are sequentially reading a file, the kernel reads some data in advance (ahead) to reduce the amount of time that processes need to wait for data to be available. The actual amount of data being read in advance is computed dynamically, based on how much "sequential" the I/O seems to be. This parameter sets the maximum amount of data that the kernel reads ahead for a single file. If you observe that large sequential reads from a file are not fast enough, you can try increasing this value. Increasing it too far may result in readahead thrashing where pagecache used for readahead is reclaimed before it can be used, or slowdowns because of a large amount of useless I/O. The default value is 512 (KB).

14.3.5 Transparent Huge Page Parameters

Transparent Huge Pages (THP) provide a way to dynamically allocate huge pages either on‑demand by the process or deferring the allocation until later via the khugepaged kernel thread. This method is distinct from the use of hugetlbfs to manually manage their allocation and use. Workloads with contiguous memory access patterns can benefit greatly from THP. A 1000-fold decrease in page faults can be observed when running synthetic workloads with contiguous memory access patterns.

There are cases when THP may be undesirable. Workloads with sparse memory access patterns can perform poorly with THP due to excessive memory usage. For example, 2 MB of memory may be used at fault time instead of 4 KB for each fault and ultimately lead to premature page reclaim. On releases older than SUSE Linux Enterprise 12 SP2, it was possible for an application to stall for long periods of time trying to allocate a THP which frequently led to a recommendation of disabling THP. Such recommendations should be re-evaluated for SUSE Linux Enterprise 12 SP3

The behavior of THP may be configured via the transparent_hugepage= kernel parameter or via sysfs. For example, it may be disabled by adding the kernel parameter transparent_hugepage=never, rebuilding your grub2 configuration, and rebooting. Verify if THP is disabled with:

root # cat /sys/kernel/mm/transparent_hugepage/enabled
always madvise [never]

If disabled, the value never is shown in square brackets like in the example above. A value of always will always try and use THP at fault time but defer to khugepaged if the allocation fails. A value of madvise will only allocate THP for address spaces explicitly specified by an application.

/sys/kernel/mm/transparent_hugepage/defrag

This parameter controls how much effort an application commits when allocating a THP. A value of always is the default for SUSE Linux Enterprise 12 SP1 and earlier releases that supported THP. If a THP is not available, the application will try to defragment memory. It potentially incurs large stalls in an application if the memory is fragmented and a THP is not available.

A value of madvise means that THP allocation requests will only defragment if the application explicitly requests it. This is the default for SUSE Linux Enterprise 12 SP2 and later releases.

defer is only available on SUSE Linux Enterprise 12 SP2 and later releases. If a THP is not available, the application will fall back to using small pages if a THP is not available. It will wake the kswapd and kcompactd kernel threads to defragment memory in the background and a THP will be allocated later by khugepaged.

The final option never will use small pages if a THP is unavailable but no other action will take place.

14.3.6 khugepaged Parameters

khugepaged will be automatically started when transparent_hugepage is set to always or madvise, and it will be automatically shut down if it is set to never. Normally this runs at low frequency but the behavior can be tuned.

/sys/kernel/mm/transparent_hugepage/khugepaged/defrag

A value of 0 will disable khugepaged even though THP may still be used at fault time. This may be important for latency-sensitive applications that benefit from THP but cannot tolerate a stall if khugepaged tries to update an application memory usage.

/sys/kernel/mm/transparent_hugepage/khugepaged/pages_to_scan

This parameter controls how many pages are scanned by khugepaged in a single pass. A scan identifies small pages that can be reallocated as THP. Increasing this value will allocate THP in the background faster at the cost of CPU usage.

/sys/kernel/mm/transparent_hugepage/khugepaged/scan_sleep_millisecs

khugepaged sleeps for a short interval specified by this parameter after each pass to limit how much CPU usage is used. Reducing this value will allocate THP in the background faster at the cost of CPU usage. A value of 0 will force continual scanning.

/sys/kernel/mm/transparent_hugepage/khugepaged/alloc_sleep_millisecs

This parameter controls how long khugepaged will sleep in the event it fails to allocate a THP in the background waiting for kswapd and kcompactd to take action.

The remaining parameters for khugepaged are rarely useful for performance tuning but are fully documented in /usr/src/linux/Documentation/vm/transhuge.txt

14.3.7 Further VM Parameters

For the complete list of the VM tunable parameters, see /usr/src/linux/Documentation/sysctl/vm.txt (available after having installed the kernel-source package).

14.4 Monitoring VM Behavior

Some simple tools that can help monitor VM behavior:

  1. vmstat: This tool gives a good overview of what the VM is doing. See Section 2.1.1, “vmstat for details.

  2. /proc/meminfo: This file gives a detailed breakdown of where memory is being used. See Section 2.4.2, “Detailed Memory Usage: /proc/meminfo for details.

  3. slabtop: This tool provides detailed information about kernel slab memory usage. buffer_head, dentry, inode_cache, ext3_inode_cache, etc. are the major caches. This command is available with the package procps.

  4. /proc/vmstat: This file gives a detailed breakdown of internal VM behaviour. The information contained within is implementation specific and may not always be available. Some information is duplicated in /proc/meminfo and other can be presented in a friendly fashion by utilities. For maximum utility, this file needs to be monitored over time to observe rates of change. The most important pieces of information that are hard to derive from other sources are as follows:

    pgscan_kswapd_*, pgsteal_kswapd_*

    These report respectively the number of pages scanned and reclaimed by kswapd since the system started. The ratio between these values can be interpreted as the reclaim efficiency with a low efficiency implying that the system is struggling to reclaim memory and may be thrashing. Light activity here is generally not something to be concerned with.

    pgscan_direct_*, pgsteal_direct_*

    These report respectively the number of pages scanned and reclaimed by an application directly. This is correlated with increases in the allocstall counter. This is more serious than kswapd activity as these events indicate that processes are stalling. Heavy activity here combined with kswapd and high rates of pgpgin, pgpout and/or high rates of pswapin or pswpout are signs that a system is thrashing heavily.

    More detailed information can be obtained using tracepoints.

    thp_fault_alloc, thp_fault_fallback

    These counters correspond to how many THPs were allocated directly by an application and how many times a THP was not available and small pages were used. Generally a high fallback rate is harmless unless the application is very sensitive to TLB pressure.

    thp_collapse_alloc, thp_collapse_alloc_failed

    These counters correspond to how many THPs were allocated by khugepaged and how many times a THP was not available and small pages were used. A high fallback rate implies that the system is fragmented and THPs are not being used even when the memory usage by applications would allow them. It is only a problem for applications that are sensitive to TLB pressure.

    compact_*_scanned, compact_stall, compact_fail, compact_success

    These counters may increase when THP is enabled and the system is fragmented. compact_stall is incremented when an application stalls allocating THP. The remaining counters account for pages scanned, the number of defragmentation events that succeeded or failed.

15 Tuning the Network

  • Filename: tuning_network.xml
  • ID: cha.tuning.network

The network subsystem is complex and its tuning highly depends on the system use scenario and on external factors such as software clients or hardware components (switches, routers, or gateways) in your network. The Linux kernel aims more at reliability and low latency than low overhead and high throughput. Other settings can mean less security, but better performance.

15.1 Configurable Kernel Socket Buffers

Networking is largely based on the TCP/IP protocol and a socket interface for communication; for more information about TCP/IP, see Chapter 16, Basic Networking. The Linux kernel handles data it receives or sends via the socket interface in socket buffers. These kernel socket buffers are tunable.

Important
Important: TCP Autotuning

Since kernel version 2.6.17 full autotuning with 4 MB maximum buffer size exists. This means that manual tuning usually will not improve networking performance considerably. It is often the best not to touch the following variables, or, at least, to check the outcome of tuning efforts carefully.

If you update from an older kernel, it is recommended to remove manual TCP tunings in favor of the autotuning feature.

The special files in the /proc file system can modify the size and behavior of kernel socket buffers; for general information about the /proc file system, see Section 2.6, “The /proc File System”. Find networking related files in:

/proc/sys/net/core
/proc/sys/net/ipv4
/proc/sys/net/ipv6

General net variables are explained in the kernel documentation (linux/Documentation/sysctl/net.txt). Special ipv4 variables are explained in linux/Documentation/networking/ip-sysctl.txt and linux/Documentation/networking/ipvs-sysctl.txt.

In the /proc file system, for example, it is possible to either set the Maximum Socket Receive Buffer and Maximum Socket Send Buffer for all protocols, or both these options for the TCP protocol only (in ipv4) and thus overriding the setting for all protocols (in core).

/proc/sys/net/ipv4/tcp_moderate_rcvbuf

If /proc/sys/net/ipv4/tcp_moderate_rcvbuf is set to 1, autotuning is active and buffer size is adjusted dynamically.

/proc/sys/net/ipv4/tcp_rmem

The three values setting the minimum, initial, and maximum size of the Memory Receive Buffer per connection. They define the actual memory usage, not only TCP window size.

/proc/sys/net/ipv4/tcp_wmem

The same as tcp_rmem, but for Memory Send Buffer per connection.

/proc/sys/net/core/rmem_max

Set to limit the maximum receive buffer size that applications can request.

/proc/sys/net/core/wmem_max

Set to limit the maximum send buffer size that applications can request.

Via /proc it is possible to disable TCP features that you do not need (all TCP features are switched on by default). For example, check the following files:

/proc/sys/net/ipv4/tcp_timestamps

TCP time stamps are defined in RFC1323.

/proc/sys/net/ipv4/tcp_window_scaling

TCP window scaling is also defined in RFC1323.

/proc/sys/net/ipv4/tcp_sack

Select acknowledgments (SACKS).

Use sysctl to read or write variables of the /proc file system. sysctl is preferable to cat (for reading) and echo (for writing), because it also reads settings from /etc/sysctl.conf and, thus, those settings survive reboots reliably. With sysctl you can read all variables and their values easily; as root use the following command to list TCP related settings:

sysctl -a | grep tcp
Note
Note: Side-Effects of Tuning Network Variables

Tuning network variables can affect other system resources such as CPU or memory use.

15.2 Detecting Network Bottlenecks and Analyzing Network Traffic

Before starting with network tuning, it is important to isolate network bottlenecks and network traffic patterns. There are some tools that can help you with detecting those bottlenecks.

The following tools can help analyzing your network traffic: netstat, tcpdump, and wireshark. Wireshark is a network traffic analyzer.

15.3 Netfilter

The Linux firewall and masquerading features are provided by the Netfilter kernel modules. This is a highly configurable rule based framework. If a rule matches a packet, Netfilter accepts or denies it or takes special action (target) as defined by rules such as address translation.

There are quite a lot of properties Netfilter can take into account. Thus, the more rules are defined, the longer packet processing may last. Also advanced connection tracking could be rather expensive and, thus, slowing down overall networking.

When the kernel queue becomes full, all new packets are dropped, causing existing connections to fail. The 'fail-open' feature allows a user to temporarily disable the packet inspection and maintain the connectivity under heavy network traffic. For reference, see https://home.regit.org/netfilter-en/using-nfqueue-and-libnetfilter_queue/.

For more information, see the home page of the Netfilter and iptables project, http://www.netfilter.org

15.4 Improving the Network Performance with Receive Packet Steering (RPS)

Modern network interface devices can move so many packets that the host can become the limiting factor for achieving maximum performance. To keep up, the system must be able to distribute the work across multiple CPU cores.

Some modern network interfaces can help distribute the work to multiple CPU cores through the implementation of multiple transmission and multiple receive queues in hardware. However, others are only equipped with a single queue and the driver must deal with all incoming packets in a single, serialized stream. To work around this issue, the operating system must "parallelize" the stream to distribute the work across multiple CPUs. On SUSE Linux Enterprise Server this is done via Receive Packet Steering (RPS). RPS can also be used in virtual environments.

RPS creates a unique hash for each data stream using IP addresses and port numbers. The use of this hash ensures that packets for the same data stream are sent to the same CPU, which helps to increase performance.

RPS is configured per network device receive queue and interface. The configuration file names match the following scheme:

/sys/class/net/<device>/queues/<rx-queue>/rps_cpus

<device> stands for the network device, such as eth0, eth1. <rx-queue> stands for the receive queue, such as rx-0, rx-1.

If the network interface hardware only supports a single receive queue, only rx-0 will exist. If it supports multiple receive queues, there will be an rx-N directory for each receive queue.

These configuration files contain a comma-delimited list of CPU bitmaps. By default, all bits are set to 0. With this setting RPS is disabled and therefore the CPU that handles the interrupt will also process the packet queue.

To enable RPS and enable specific CPUs to process packets for the receive queue of the interface, set the value of their positions in the bitmap to 1. For example, to enable CPUs 0-3 to process packets for the first receive queue for eth0, set the bit positions 0-3 to 1 in binary: 00001111. This representation then needs to be converted to hex—which results in F in this case. Set this hex value with the following command:

echo "f" > /sys/class/net/eth0/queues/rx-0/rps_cpus

If you wanted to enable CPUs 8-15:

1111 1111 0000 0000 (binary)
15     15    0    0 (decimal)
F       F    0    0 (hex)

The command to set the hex value of ff00 would be:

echo "ff00" > /sys/class/net/eth0/queues/rx-0/rps_cpus

On NUMA machines, best performance can be achieved by configuring RPS to use the CPUs on the same NUMA node as the interrupt for the interface's receive queue.

On non-NUMA machines, all CPUs can be used. If the interrupt rate is very high, excluding the CPU handling the network interface can boost performance. The CPU being used for the network interface can be determined from /proc/interrupts. For example:

root # cat /proc/interrupts
            CPU0       CPU1       CPU2       CPU3
...
  51:  113915241          0          0          0      Phys-fasteoi   eth0
...

In this case, CPU 0 is the only CPU processing interrupts for eth0, since only CPU0 contains a non-zero value.

On x86 and AMD64/Intel 64 platforms, irqbalance can be used to distribute hardware interrupts across CPUs. See man 1 irqbalance for more details.

15.5 For More Information

Part VI Handling System Dumps

16 Tracing Tools

SUSE Linux Enterprise Server comes with several tools that help you obtain useful information about your system. You can use the information for various purposes, for example, to debug and find problems in your program, to discover places causing performance drops, or to trace a running process to f…

17 Kexec and Kdump

Kexec is a tool to boot to another kernel from the currently running one. You can perform faster system reboots without any hardware initialization. You can also prepare the system to boot to another kernel if the system crashes.

16 Tracing Tools

  • Filename: tuning_tracing.xml
  • ID: cha.tuning.tracing

SUSE Linux Enterprise Server comes with several tools that help you obtain useful information about your system. You can use the information for various purposes, for example, to debug and find problems in your program, to discover places causing performance drops, or to trace a running process to find out what system resources it uses. Most of the tools are part of the installation media. In some cases, they need to be installed from the SUSE Software Development Kit, which is a separate download.

Note
Note: Tracing and Impact on Performance

While a running process is being monitored for system or library calls, the performance of the process is heavily reduced. You are advised to use tracing tools only for the time you need to collect the data.

16.1 Tracing System Calls with strace

The strace command traces system calls of a process and signals received by the process. strace can either run a new command and trace its system calls, or you can attach strace to an already running command. Each line of the command's output contains the system call name, followed by its arguments in parentheses and its return value.

To run a new command and start tracing its system calls, enter the command to be monitored as you normally do, and add strace at the beginning of the command line:

tux > strace ls
execve("/bin/ls", ["ls"], [/* 52 vars */]) = 0
brk(0)                                  = 0x618000
mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) \
        = 0x7f9848667000
mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) \
        = 0x7f9848666000
access("/etc/ld.so.preload", R_OK)      = -1 ENOENT \
(No such file or directory)
open("/etc/ld.so.cache", O_RDONLY)      = 3
fstat(3, {st_mode=S_IFREG|0644, st_size=200411, ...}) = 0
mmap(NULL, 200411, PROT_READ, MAP_PRIVATE, 3, 0) = 0x7f9848635000
close(3)                                = 0
open("/lib64/librt.so.1", O_RDONLY)     = 3
[...]
mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) \
= 0x7fd780f79000
write(1, "Desktop\nDocuments\nbin\ninst-sys\n", 31Desktop
Documents
bin
inst-sys
) = 31
close(1)                                = 0
munmap(0x7fd780f79000, 4096)            = 0
close(2)                                = 0
exit_group(0)                           = ?

To attach strace to an already running process, you need to specify the -p with the process ID (PID) of the process that you want to monitor:

tux > strace -p `pidof cron`
 Process 1261 attached
 restart_syscall(<... resuming interrupted call ...>) = 0
  stat("/etc/localtime", {st_mode=S_IFREG|0644, st_size=2309, ...}) = 0
  select(5, [4], NULL, NULL, {0, 0})      = 0 (Timeout)
  socket(PF_LOCAL, SOCK_STREAM|SOCK_CLOEXEC|SOCK_NONBLOCK, 0) = 5
  connect(5, {sa_family=AF_LOCAL, sun_path="/var/run/nscd/socket"}, 110) = 0
  sendto(5, "\2\0\0\0\0\0\0\0\5\0\0\0root\0", 17, MSG_NOSIGNAL, NULL, 0) = 17
  poll([{fd=5, events=POLLIN|POLLERR|POLLHUP}], 1, 5000) = 1 ([{fd=5, revents=POLLIN|POLLHUP}])
  read(5, "\2\0\0\0\1\0\0\0\5\0\0\0\2\0\0\0\0\0\0\0\0\0\0\0\5\0\0\0\6\0\0\0"..., 36) = 36
  read(5, "root\0x\0root\0/root\0/bin/bash\0", 28) = 28
  close(5)                                = 0
  rt_sigprocmask(SIG_BLOCK, [CHLD], [], 8) = 0
  rt_sigaction(SIGCHLD, NULL, {0x7f772b9ea890, [], SA_RESTORER|SA_RESTART, 0x7f772adf7880}, 8) = 0
  rt_sigprocmask(SIG_SETMASK, [], NULL, 8) = 0
  nanosleep({60, 0}, 0x7fff87d8c580)      = 0
  stat("/etc/localtime", {st_mode=S_IFREG|0644, st_size=2309, ...}) = 0
  select(5, [4], NULL, NULL, {0, 0})      = 0 (Timeout)
  socket(PF_LOCAL, SOCK_STREAM|SOCK_CLOEXEC|SOCK_NONBLOCK, 0) = 5
  connect(5, {sa_family=AF_LOCAL, sun_path="/var/run/nscd/socket"}, 110) = 0
  sendto(5, "\2\0\0\0\0\0\0\0\5\0\0\0root\0", 17, MSG_NOSIGNAL, NULL, 0) = 17
  poll([{fd=5, events=POLLIN|POLLERR|POLLHUP}], 1, 5000) = 1 ([{fd=5, revents=POLLIN|POLLHUP}])
  read(5, "\2\0\0\0\1\0\0\0\5\0\0\0\2\0\0\0\0\0\0\0\0\0\0\0\5\0\0\0\6\0\0\0"..., 36) = 36
  read(5, "root\0x\0root\0/root\0/bin/bash\0", 28) = 28
  close(5)
  [...]

The -e option understands several sub-options and arguments. For example, to trace all attempts to open or write to a particular file, use the following:

tux > strace -e trace=open,write ls ~
open("/etc/ld.so.cache", O_RDONLY)       = 3
open("/lib64/librt.so.1", O_RDONLY)      = 3
open("/lib64/libselinux.so.1", O_RDONLY) = 3
open("/lib64/libacl.so.1", O_RDONLY)     = 3
open("/lib64/libc.so.6", O_RDONLY)       = 3
open("/lib64/libpthread.so.0", O_RDONLY) = 3
[...]
open("/usr/lib/locale/cs_CZ.utf8/LC_CTYPE", O_RDONLY) = 3
open(".", O_RDONLY|O_NONBLOCK|O_DIRECTORY|O_CLOEXEC) = 3
write(1, "addressbook.db.bak\nbin\ncxoffice\n"..., 311) = 311

To trace only network related system calls, use -e trace=network:

tux > strace -e trace=network -p 26520
Process 26520 attached - interrupt to quit
socket(PF_NETLINK, SOCK_RAW, 0)         = 50
bind(50, {sa_family=AF_NETLINK, pid=0, groups=00000000}, 12) = 0
getsockname(50, {sa_family=AF_NETLINK, pid=26520, groups=00000000}, \
[12]) = 0
sendto(50, "\24\0\0\0\26\0\1\3~p\315K\0\0\0\0\0\0\0\0", 20, 0,
{sa_family=AF_NETLINK, pid=0, groups=00000000}, 12) = 20
[...]

The -c calculates the time the kernel spent on each system call:

tux > strace -c find /etc -name xorg.conf
/etc/X11/xorg.conf
% time     seconds  usecs/call     calls    errors syscall
------ ----------- ----------- --------- --------- ----------------
 32.38    0.000181         181         1           execve
 22.00    0.000123           0       576           getdents64
 19.50    0.000109           0       917        31 open
 19.14    0.000107           0       888           close
  4.11    0.000023           2        10           mprotect
  0.00    0.000000           0         1           write
[...]
  0.00    0.000000           0         1           getrlimit
  0.00    0.000000           0         1           arch_prctl
  0.00    0.000000           0         3         1 futex
  0.00    0.000000           0         1           set_tid_address
  0.00    0.000000           0         4           fadvise64
  0.00    0.000000           0         1           set_robust_list
------ ----------- ----------- --------- --------- ----------------
100.00    0.000559                  3633        33 total

To trace all child processes of a process, use -f:

tux > strace -f rcapache2 status
execve("/usr/sbin/rcapache2", ["rcapache2", "status"], [/* 81 vars */]) = 0
brk(0)                                  = 0x69e000
mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) \
= 0x7f3bb553b000
mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) \
= 0x7f3bb553a000
[...]
[pid  4823] rt_sigprocmask(SIG_SETMASK, [],  <unfinished ...>
[pid  4822] close(4 <unfinished ...>
[pid  4823] <... rt_sigprocmask resumed> NULL, 8) = 0
[pid  4822] <... close resumed> )       = 0
[...]
[pid  4825] mprotect(0x7fc42cbbd000, 16384, PROT_READ) = 0
[pid  4825] mprotect(0x60a000, 4096, PROT_READ) = 0
[pid  4825] mprotect(0x7fc42cde4000, 4096, PROT_READ) = 0
[pid  4825] munmap(0x7fc42cda2000, 261953) = 0
[...]
[pid  4830] munmap(0x7fb1fff10000, 261953) = 0
[pid  4830] rt_sigprocmask(SIG_BLOCK, NULL, [], 8) = 0
[pid  4830] open("/dev/tty", O_RDWR|O_NONBLOCK) = 3
[pid  4830] close(3)
[...]
read(255, "\n\n# Inform the caller not only v"..., 8192) = 73
rt_sigprocmask(SIG_BLOCK, NULL, [], 8)  = 0
rt_sigprocmask(SIG_BLOCK, NULL, [], 8)  = 0
exit_group(0)

If you need to analyze the output of strace and the output messages are too long to be inspected directly in the console window, use -o. In that case, unnecessary messages, such as information about attaching and detaching processes, are suppressed. You can also suppress these messages (normally printed on the standard output) with -q. To add time stamps at the beginning of each line with a system call, use -t:

tux > strace -t -o strace_sleep.txt sleep 1; more strace_sleep.txt
08:44:06 execve("/bin/sleep", ["sleep", "1"], [/* 81 vars */]) = 0
08:44:06 brk(0)                         = 0x606000
08:44:06 mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, \
-1, 0) = 0x7f8e78cc5000
[...]
08:44:06 close(3)                       = 0
08:44:06 nanosleep({1, 0}, NULL)        = 0
08:44:07 close(1)                       = 0
08:44:07 close(2)                       = 0
08:44:07 exit_group(0)                  = ?

The behavior and output format of strace can be largely controlled. For more information, see the relevant manual page (man 1 strace).

16.2 Tracing Library Calls with ltrace

ltrace traces dynamic library calls of a process. It is used in a similar way to strace, and most of their parameters have a very similar or identical meaning. By default, ltrace uses /etc/ltrace.conf or ~/.ltrace.conf configuration files. You can, however, specify an alternative one with the -F CONFIG_FILE option.

In addition to library calls, ltrace with the -S option can trace system calls as well:

tux > ltrace -S -o ltrace_find.txt find /etc -name \
xorg.conf; more ltrace_find.txt
SYS_brk(NULL)                                              = 0x00628000
SYS_mmap(0, 4096, 3, 34, 0xffffffff)                       = 0x7f1327ea1000
SYS_mmap(0, 4096, 3, 34, 0xffffffff)                       = 0x7f1327ea0000
[...]
fnmatch("xorg.conf", "xorg.conf", 0)                       = 0
free(0x0062db80)                                           = <void>
__errno_location()                                         = 0x7f1327e5d698
__ctype_get_mb_cur_max(0x7fff25227af0, 8192, 0x62e020, -1, 0) = 6
__ctype_get_mb_cur_max(0x7fff25227af0, 18, 0x7f1327e5d6f0, 0x7fff25227af0,
0x62e031) = 6
__fprintf_chk(0x7f1327821780, 1, 0x420cf7, 0x7fff25227af0, 0x62e031
<unfinished ...>
SYS_fstat(1, 0x7fff25227230)                               = 0
SYS_mmap(0, 4096, 3, 34, 0xffffffff)                       = 0x7f1327e72000
SYS_write(1, "/etc/X11/xorg.conf\n", 19)                   = 19
[...]

You can change the type of traced events with the -e option. The following example prints library calls related to fnmatch and strlen functions:

tux > ltrace -e fnmatch,strlen find /etc -name xorg.conf
[...]
fnmatch("xorg.conf", "xorg.conf", 0)             = 0
strlen("Xresources")                             = 10
strlen("Xresources")                             = 10
strlen("Xresources")                             = 10
fnmatch("xorg.conf", "Xresources", 0)            = 1
strlen("xorg.conf.install")                      = 17
[...]

To display only the symbols included in a specific library, use -l /path/to/library:

tux > ltrace -l /lib64/librt.so.1 sleep 1
clock_gettime(1, 0x7fff4b5c34d0, 0, 0, 0)                  = 0
clock_gettime(1, 0x7fff4b5c34c0, 0xffffffffff600180, -1, 0) = 0
+++ exited (status 0) +++

You can make the output more readable by indenting each nested call by the specified number of space with the -n NUM_OF_SPACES.

16.3 Debugging and Profiling with Valgrind

Valgrind is a set of tools to debug and profile your programs so that they can run both faster and with less errors. Valgrind can detect problems related to memory management and threading, or can also serve as a framework for building new debugging tools. It is well known that this tool can incur high overhead, causing, for example, higher runtimes or changing the normal program behavior under concurrent workloads based on timing.

16.3.1 Installation

Valgrind is not shipped with standard SUSE Linux Enterprise Server distribution. To install it on your system, you need to obtain SUSE Software Development Kit, and either install it and run

zypper install VALGRIND

or browse through the SUSE Software Development Kit directory tree, locate the Valgrind package and install it with

rpm -i valgrind-VERSION_ARCHITECTURE.rpm

The SDK is a module for SUSE Linux Enterprise and is available via an online channel from the SUSE Customer Center. Alternatively download it from http://download.suse.com/. (Search for SUSE Linux Enterprise Software Development Kit). Refer to Chapter 14, Installing Modules, Extensions, and Third Party Add-On Products for details.

16.3.2 Supported Architectures

SUSE Linux Enterprise Server supports Valgrind on the following architectures:

  • AMD64/Intel 64

  • POWER

  • z Systems

16.3.3 General Information

The main advantage of Valgrind is that it works with existing compiled executables. You do not need to recompile or modify your programs to use it. Run Valgrind like this:

valgrind VALGRIND_OPTIONS your-prog YOUR-PROGRAM-OPTIONS

Valgrind consists of several tools, and each provides specific functionality. Information in this section is general and valid regardless of the used tool. The most important configuration option is --tool. This option tells Valgrind which tool to run. If you omit this option, memcheck is selected by default. For example, to run find ~ -name .bashrc with Valgrind's memcheck tools, enter the following in the command line:

valgrind --tool=memcheck find ~ -name .bashrc

A list of standard Valgrind tools with a brief description follows:

memcheck

Detects memory errors. It helps you tune your programs to behave correctly.

cachegrind

Profiles cache prediction. It helps you tune your programs to run faster.

callgrind

Works in a similar way to cachegrind but also gathers additional cache-profiling information.

exp-drd

Detects thread errors. It helps you tune your multi-threaded programs to behave correctly.

helgrind

Another thread error detector. Similar to exp-drd but uses different techniques for problem analysis.

massif

A heap profiler. Heap is an area of memory used for dynamic memory allocation. This tool helps you tune your program to use less memory.

lackey

An example tool showing instrumentation basics.

16.3.4 Default Options

Valgrind can read options at start-up. There are three places which Valgrind checks:

  1. The file .valgrindrc in the home directory of the user who runs Valgrind.

  2. The environment variable $VALGRIND_OPTS

  3. The file .valgrindrc in the current directory where Valgrind is run from.

These resources are parsed exactly in this order, while later given options take precedence over earlier processed options. Options specific to a particular Valgrind tool must be prefixed with the tool name and a colon. For example, if you want cachegrind to always write profile data to the /tmp/cachegrind_PID.log, add the following line to the .valgrindrc file in your home directory:

--cachegrind:cachegrind-out-file=/tmp/cachegrind_%p.log

16.3.5 How Valgrind Works

Valgrind takes control of your executable before it starts. It reads debugging information from the executable and related shared libraries. The executable's code is redirected to the selected Valgrind tool, and the tool adds its own code to handle its debugging. Then the code is handed back to the Valgrind core and the execution continues.

For example, memcheck adds its code, which checks every memory access. As a consequence, the program runs much slower than in the native execution environment.

Valgrind simulates every instruction of your program. Therefore, it not only checks the code of your program, but also all related libraries (including the C library), libraries used for graphical environment, and so on. If you try to detect errors with Valgrind, it also detects errors in associated libraries (like C, X11, or Gtk libraries). Because you probably do not need these errors, Valgrind can selectively, suppress these error messages to suppression files. The --gen-suppressions=yes tells Valgrind to report these suppressions which you can copy to a file.

You should supply a real executable (machine code) as a Valgrind argument. If your application is run, for example, from a shell or Perl script, you will by mistake get error reports related to /bin/sh (or /usr/bin/perl). In such cases, you can use --trace-children=yes to work around this issue. However, using the executable itself will avoid any confusion over this issue.

16.3.6 Messages

During its runtime, Valgrind reports messages with detailed errors and important events. The following example explains the messages:

tux > valgrind --tool=memcheck find ~ -name .bashrc
[...]
==6558== Conditional jump or move depends on uninitialised value(s)
==6558==    at 0x400AE79: _dl_relocate_object (in /lib64/ld-2.11.1.so)
==6558==    by 0x4003868: dl_main (in /lib64/ld-2.11.1.so)
[...]
==6558== Conditional jump or move depends on uninitialised value(s)
==6558==    at 0x400AE82: _dl_relocate_object (in /lib64/ld-2.11.1.so)
==6558==    by 0x4003868: dl_main (in /lib64/ld-2.11.1.so)
[...]
==6558== ERROR SUMMARY: 2 errors from 2 contexts (suppressed: 0 from 0)
==6558== malloc/free: in use at exit: 2,228 bytes in 8 blocks.
==6558== malloc/free: 235 allocs, 227 frees, 489,675 bytes allocated.
==6558== For counts of detected errors, rerun with: -v
==6558== searching for pointers to 8 not-freed blocks.
==6558== checked 122,584 bytes.
==6558==
==6558== LEAK SUMMARY:
==6558==    definitely lost: 0 bytes in 0 blocks.
==6558==      possibly lost: 0 bytes in 0 blocks.
==6558==    still reachable: 2,228 bytes in 8 blocks.
==6558==         suppressed: 0 bytes in 0 blocks.
==6558== Rerun with --leak-check=full to see details of leaked memory.

The ==6558== introduces Valgrind's messages and contains the process ID number (PID). You can easily distinguish Valgrind's messages from the output of the program itself, and decide which messages belong to a particular process.

To make Valgrind's messages more detailed, use -v or even -v -v.

You can make Valgrind send its messages to three different places:

  1. By default, Valgrind sends its messages to the file descriptor 2, which is the standard error output. You can tell Valgrind to send its messages to any other file descriptor with the --log-fd=FILE_DESCRIPTOR_NUMBER option.

  2. The second and probably more useful way is to send Valgrind's messages to a file with --log-file=FILENAME. This option accepts several variables, for example, %p gets replaced with the PID of the currently profiled process. This way you can send messages to different files based on their PID. %q{env_var} is replaced with the value of the related env_var environment variable.

    The following example checks for possible memory errors during the Apache Web server restart, while following children processes and writing detailed Valgrind's messages to separate files distinguished by the current process PID:

    tux > valgrind -v --tool=memcheck --trace-children=yes \
    --log-file=valgrind_pid_%p.log rcapache2 restart

    This process created 52 log files in the testing system, and took 75 seconds instead of the usual 7 seconds needed to run sudo systemctl restart apache2 without Valgrind, which is approximately 10 times more.

    tux > ls -1 valgrind_pid_*log
    valgrind_pid_11780.log
    valgrind_pid_11782.log
    valgrind_pid_11783.log
    [...]
    valgrind_pid_11860.log
    valgrind_pid_11862.log
    valgrind_pid_11863.log
  3. You may also prefer to send the Valgrind's messages over the network. You need to specify the aa.bb.cc.dd IP address and port_num port number of the network socket with the --log-socket=AA.BB.CC.DD:PORT_NUM option. If you omit the port number, 1500 will be used.

    It is useless to send Valgrind's messages to a network socket if no application is capable of receiving them on the remote machine. That is why valgrind-listener, a simple listener, is shipped together with Valgrind. It accepts connections on the specified port and copies everything it receives to the standard output.

16.3.7 Error Messages

Valgrind remembers all error messages, and if it detects a new error, the error is compared against old error messages. This way Valgrind checks for duplicate error messages. In case of a duplicate error, it is recorded but no message is shown. This mechanism prevents you from being overwhelmed by millions of duplicate errors.

The -v option will add a summary of all reports (sorted by their total count) to the end of the Valgrind's execution output. Moreover, Valgrind stops collecting errors if it detects either 1000 different errors, or 10 000 000 errors in total. If you want to suppress this limit and wish to see all error messages, use --error-limit=no.

Some errors usually cause other ones. Therefore, fix errors in the same order as they appear and re-check the program continuously.

16.4 For More Information

  • For a complete list of options related to the described tracing tools, see the corresponding man page (man 1 strace, man 1 ltrace, and man 1 valgrind).

  • To describe advanced usage of Valgrind is beyond the scope of this document. It is very well documented, see Valgrind User Manual. These pages are indispensable if you need more advanced information on Valgrind or the usage and purpose of its standard tools.

17 Kexec and Kdump

  • Filename: tuning_kexec.xml
  • ID: cha.tuning.kexec

Kexec is a tool to boot to another kernel from the currently running one. You can perform faster system reboots without any hardware initialization. You can also prepare the system to boot to another kernel if the system crashes.

17.1 Introduction

With Kexec, you can replace the running kernel with another one without a hard reboot. The tool is useful for several reasons:

  • Faster system rebooting

    If you need to reboot the system frequently, Kexec can save you significant time.

  • Avoiding unreliable firmware and hardware

    Computer hardware is complex and serious problems may occur during the system start-up. You cannot always replace unreliable hardware immediately. Kexec boots the kernel to a controlled environment with the hardware already initialized. The risk of unsuccessful system start is then minimized.

  • Saving the dump of a crashed kernel

    Kexec preserves the contents of the physical memory. After the production kernel fails, the capture kernel (an additional kernel running in a reserved memory range) saves the state of the failed kernel. The saved image can help you with the subsequent analysis.

  • Booting without GRUB 2 configuration

    When the system boots a kernel with Kexec, it skips the boot loader stage. The normal booting procedure can fail because of an error in the boot loader configuration. With Kexec, you do not depend on a working boot loader configuration.

17.2 Required Packages

To use Kexec on SUSE® Linux Enterprise Server to speed up reboots or avoid potential hardware problems, make sure that the package kexec-tools is installed. It contains a script called kexec-bootloader, which reads the boot loader configuration and runs Kexec using the same kernel options as the normal boot loader.

To set up an environment that helps you obtain debug information in case of a kernel crash, make sure that the package makedumpfile is installed.

The preferred method of using Kdump in SUSE Linux Enterprise Server is through the YaST Kdump module. To use the YaST module, make sure that the package yast2-kdump is installed.

17.3 Kexec Internals

The most important component of Kexec is the /sbin/kexec command. You can load a kernel with Kexec in two different ways:

  • Load the kernel to the address space of a production kernel for a regular reboot:

    root # kexec -l KERNEL_IMAGE

    You can later boot to this kernel with kexec -e.

  • Load the kernel to a reserved area of memory:

    root # kexec -p KERNEL_IMAGE

    This kernel will be booted automatically when the system crashes.

If you want to boot another kernel and preserve the data of the production kernel when the system crashes, you need to reserve a dedicated area of the system memory. The production kernel never loads to this area because it must be always available. It is used for the capture kernel so that the memory pages of the production kernel can be preserved.

To reserve the area, append the option crashkernel to the boot command line of the production kernel. To determine the necessary values for crashkernel, follow the instructions in Section 17.4, “Calculating crashkernel Allocation Size”.

Note that this is not a parameter of the capture kernel. The capture kernel does not use Kexec.

The capture kernel is loaded to the reserved area and waits for the kernel to crash. Then, Kdump tries to invoke the capture kernel because the production kernel is no longer reliable at this stage. This means that even Kdump can fail.

To load the capture kernel, you need to include the kernel boot parameters. Usually, the initial RAM file system is used for booting. You can specify it with --initrd=FILENAME. With --append=CMDLINE, you append options to the command line of the kernel to boot.

It is helpful to include the command line of the production kernel if these options are necessary for the kernel to boot. You can simply copy the command line with --append="$(cat /proc/cmdline)" or add more options with --append="$(cat /proc/cmdline) more_options".

You can always unload the previously loaded kernel. To unload a kernel that was loaded with the -l option, use the kexec -u command. To unload a crash kernel loaded with the -p option, use kexec -p -u command.

17.4 Calculating crashkernel Allocation Size

To use Kexec with a capture kernel and to use Kdump in any way, RAM needs to be allocated for the capture kernel. The allocation size depends on the expected hardware configuration of the computer, therefore you need to specify it.

The allocation size also depends on the hardware architecture of your computer. Make sure to follow the procedure intended for your system architecture.

Procedure 17.1: Allocation Size on AMD64/Intel 64
  1. To find out the base value for the computer, run the following in a terminal:

    root # kdumptool calibrate

    This command returns a list of values. All values are given in megabytes.

  2. Write down the values of Low and High.

    Note
    Note: Significance of Low and High Values

    On AMD64/Intel 64 computers, the High value stands for the memory reservation for all available memory. The Low value stands for the memory reservation in the DMA32 zone, that is, all the memory up to the 4 GB mark.

    If the computer has less than 4 GB of RAM, the High memory reservation is allocated and the Low memory reservation is ignored. If the computer has more than 4 GB of RAM, the Low memory reservation is allocated additionally.

  3. Adapt the High value from the previous step for the number of LUN kernel paths (paths to storage devices) attached to the computer. A sensible value in megabytes can be calculated using this formula:

    SIZE_HIGH = RECOMMENDATION + (LUNs / 2)

    The following parameters are used in this formula:

    • SIZE_HIGH.  The resulting value for High.

    • RECOMMENDATION.  The value recommended by kdumptool calibrate for High.

    • LUNs.  The maximum number of LUN kernel paths that you expect to ever create on the computer. Exclude multipath devices from this number, as these are ignored.

    Important
    Important: Adjust for Large Amounts of RAM

    For machines that have multiple terabytes (!) of RAM, such as many servers running SAP HANA, you need to additionally adjust the amount of both Kdump High and Low Memory.

    Experience suggests that in such cases, you might be successful using the following formulas:

    SIZE_HIGH = (RECOMMENDATION * RAM_IN_TB) + (LUNs / 2)
    SIZE_LOW = (RECOMMENDATION * RAM_IN_TB) + CUSTOM_DRIVER-RESERVATION_ADJUSTMENT
  4. If the drivers for your device make many reservations in the DMA32 zone, the Low value also needs to be adjusted. However, there is no simple formula to calculate these. Finding the right size can therefore be a process of trial and error.

    For the beginning, use the Low value recommended by kdumptool calibrate.

  5. The values now need to be set in the correct location.

    If you are changing the kernel command line directly

    Append the following kernel option to your boot loader configuration:

    crashkernel=SIZE_HIGH,high crashkernel=SIZE_LOW,low

    Replace the placeholders SIZE_HIGH and SIZE_LOW with the appropriate value from the previous steps and append the letter M (for megabytes).

    As an example, the following is valid:

    crashkernel=36M,high crashkernel=72M,low
    If you are using the YaST GUI:

    Set Kdump Low Memory to the determined Low value.

    Set Kdump High Memory to the determined High value.

    If you are using the YaST command line interface:

    Use the following command:

    root # yast kdump startup enable alloc_mem=LOW,HIGH

    Replace LOW with the determined Low value. Replace HIGH with the determined HIGH value.

Procedure 17.2: Allocation Size on POWER and z Systems
  1. To find out the basis value for the computer, run the following in a terminal:

    root # kdumptool calibrate

    This command returns a list of values. All values are given in megabytes.

  2. Write down the value of Low.

  3. Adapt the Low value from the previous step for the number of LUN kernel paths (paths to storage devices) attached to the computer. A sensible value in megabytes can be calculated using this formula:

    SIZE_LOW = RECOMMENDATION + (LUNs / 2)

    The following parameters are used in this formula:

    • SIZE_LOW.  The resulting value for Low.

    • RECOMMENDATION.  The value recommended by kdumptool calibrate for Low.

    • LUNs.  The maximum number of LUN kernel paths that you expect to ever create on the computer. Exclude multipath devices from this number, as these are ignored.

  4. The values now need to be set in the correct location.

    If you are working on the command line

    Append the following kernel option to your boot loader configuration:

    crashkernel=SIZE_LOW

    Replace the placeholderSIZE_LOW with the appropriate value from the previous step and append the letter M (for megabytes).

    As an example, the following is valid:

    crashkernel=108M
    If you are working in YaST

    Set Kdump Memory to the determined Low value.

Tip
Tip: Excluding Unused and Inactive CCW Devices on IBM z Systems

Depending on the number of available devices the calculated amount of memory specified by the crashkernel kernel parameter may not be sufficient. Instead of increasing the value, you may alternatively limit the amount of devices visible to the kernel. This will lower the required amount of memory for the "crashkernel" setting.

  1. To ignore devices you can run the cio_ignore tool to generate an appropriate stanza to ignore all devices, except the ones currently active or in use.

    tux > sudo cio_ignore -u -k
    cio_ignore=all,!da5d,!f500-f502

    When you run cio_ignore -u -k, the blacklist will become active and replace any existing blacklist immediately. Unused devices are not being purged, so they still appear in the channel subsystem. But adding new channel devices (via CP ATTACH under z/VM or dynamic I/O configuration change in LPAR) will treat them as blacklisted. To prevent this, preserve the original setting by running sudo cio_ignore -l first and reverting to that state after running cio_ignore -u -k. As an alternative, add the generated stanza to the regular kernel boot parameters.

  2. Now add the cio_ignore kernel parameter with the stanza from above to KDUMP_CMDLINE_APPEND in /etc/sysconfig/kdump, for example:

    KDUMP_COMMANDLINE_APPEND="cio_ignore=all,!da5d,!f500-f502"
  3. Activate the setting by restarting kdump:

    systemctl restart kdump.service

17.5 Basic Kexec Usage

To verify if your Kexec environment works properly, follow these steps:

  1. Make sure no users are currently logged in and no important services are running on the system.

  2. Log in as root.

  3. Switch to the rescue target with systemctl isolate rescue.target

  4. Load the new kernel to the address space of the production kernel with the following command:

    root # kexec -l /boot/vmlinuz --append="$(cat /proc/cmdline)" \
    --initrd=/boot/initrd
  5. Unmount all mounted file systems except the root file system with:

    umount -a
    Important
    Important: Unmounting the Root File System

    Unmounting all file systems will most likely produce a device is busy warning message. The root file system cannot be unmounted if the system is running. Ignore the warning.

  6. Remount the root file system in read-only mode:

    root # mount -o remount,ro /
  7. Initiate the reboot of the kernel that you loaded in Step 4 with:

    root # kexec -e

It is important to unmount the previously mounted disk volumes in read-write mode. The reboot system call acts immediately upon calling. Hard disk volumes mounted in read-write mode neither synchronize nor unmount automatically. The new kernel may find them dirty. Read-only disk volumes and virtual file systems do not need to be unmounted. Refer to /etc/mtab to determine which file systems you need to unmount.

The new kernel previously loaded to the address space of the older kernel rewrites it and takes control immediately. It displays the usual start-up messages. When the new kernel boots, it skips all hardware and firmware checks. Make sure no warning messages appear. All file systems are supposed to be clean if they had been unmounted.

17.6 How to Configure Kexec for Routine Reboots

Kexec is often used for frequent reboots. For example, if it takes a long time to run through the hardware detection routines or if the start-up is not reliable.

Note that firmware and the boot loader are not used when the system reboots with Kexec. Any changes you make to the boot loader configuration will be ignored until the computer performs a hard reboot.

17.7 Basic Kdump Configuration

You can use Kdump to save kernel dumps. If the kernel crashes, it is useful to copy the memory image of the crashed environment to the file system. You can then debug the dump file to find the cause of the kernel crash. This is called core dump.

Kdump works similarly to Kexec (see Chapter 17, Kexec and Kdump). The capture kernel is executed after the running production kernel crashes. The difference is that Kexec replaces the production kernel with the capture kernel. With Kdump, you still have access to the memory space of the crashed production kernel. You can save the memory snapshot of the crashed kernel in the environment of the Kdump kernel.

Tip
Tip: Dumps over Network

In environments with limited local storage, you need to set up kernel dumps over the network. Kdump supports configuring the specified network interface and bringing it up via initrd. Both LAN and VLAN interfaces are supported. Specify the network interface and the mode (DHCP or static) either with YaST, or using the KDUMP_NETCONFIG option in the /etc/sysconfig/kdump file.

Important
Important: Target File System for Kdump Must Be Mounted During Configuration

When configuring Kdump, you can specify a location to which the dumped images will be saved (default: /var/crash). This location must be mounted when configuring Kdump, otherwise the configuration will fail.

17.7.1 Manual Kdump Configuration

Kdump reads its configuration from the /etc/sysconfig/kdump file. To make sure that Kdump works on your system, its default configuration is sufficient. To use Kdump with the default settings, follow these steps:

  1. Determine the amount of memory needed for Kdump by following the instructions in Section 17.4, “Calculating crashkernel Allocation Size”. Make sure to set the kernel parameter crashkernel.

  2. Reboot the computer.

  3. Enable the Kdump service:

    root # systemctl enable kdump
  4. You can edit the options in /etc/sysconfig/kdump. Reading the comments will help you understand the meaning of individual options.

  5. Execute the init script once with sudo systemctl start kdump, or reboot the system.

After configuring Kdump with the default values, check if it works as expected. Make sure that no users are currently logged in and no important services are running on your system. Then follow these steps:

  1. Switch to the rescue target with systemctl isolate rescue.target

  2. Restart the Kdump service:

    root # systemctl start kdump
  3. Unmount all the disk file systems except the root file system with:

    root # umount -a
  4. Remount the root file system in read-only mode:

    root # mount -o remount,ro /
  5. Invoke a kernel panic with the procfs interface to Magic SysRq keys:

    root # echo c > /proc/sysrq-trigger
Important
Important: Size of Kernel Dumps

The KDUMP_KEEP_OLD_DUMPS option controls the number of preserved kernel dumps (default is 5). Without compression, the size of the dump can take up to the size of the physical RAM memory. Make sure you have sufficient space on the /var partition.

The capture kernel boots and the crashed kernel memory snapshot is saved to the file system. The save path is given by the KDUMP_SAVEDIR option and it defaults to /var/crash. If KDUMP_IMMEDIATE_REBOOT is set to yes , the system automatically reboots the production kernel. Log in and check that the dump has been created under /var/crash.

17.7.1.1 Static IP Configuration for Kdump

In case Kdump is configured to use a static IP configuration from a network device, you need to add the network configuration to the KDUMP_COMMANDLINE_APPEND variable in /etc/sysconfig/kdump.

Example 17.1: Kdump: Example Configuration Using a Static IP Setup

The following setup has been configured:

  • eth0 has been configured with the static IP address 192.168.1.1/24

  • eth1 has been configured with the static IP address 10.50.50.100/20

  • The Kdump configuration in /etc/sysconfig/kdump looks like:

    KDUMP_CPUS=1
    KDUMP_IMMEDIATE_REBOOT=yes
    KDUMP_SAVEDIR=ftp://anonymous@10.50.50.140/crashdump/
    KDUMP_KEEP_OLD_DUMPS=5
    KDUMP_FREE_DISK_SIZE=64
    KDUMP_VERBOSE=3
    KDUMP_DUMPLEVEL=31
    KDUMP_DUMPFORMAT=lzo
    KDUMP_CONTINUE_ON_ERROR=yes
    KDUMP_NETCONFIG=eth1:static
    KDUMP_NET_TIMEOUT=30

Using this configuration, Kdump fails to reach the network when trying to write the dump to the FTP server. To solve this issue, add the network configuration to KDUMP_COMMANDLINE_APPEND in /etc/sysconfig/kdump. The general pattern for this looks like the following:

KDUMP_COMMANDLINE_APPEND='ip=CLIENT IP:SERVER IP:GATEWAY IP:NETMASK:CLIENT HOSTNAME:DEVICE:PROTOCOL'

For the example configuration this would result in:

KDUMP_COMMANDLINE_APPEND='ip=10.50.50.100:10.50.50.140:10.60.48.1:255.255.240.0:dump-client:eth1:none'

17.7.2 YaST Configuration

To configure Kdump with YaST, you need to install the yast2-kdump package. Then either start the Kernel Kdump module in the System category of YaST Control Center, or enter yast2 kdump in the command line as root.

Screenshot of the YaST Kdump Module
Figure 17.1: YaST Kdump Module: Start-Up Page

In the Start-Up window, select Enable Kdump.

The values for Kdump Memory are automatically generated the first time you open the window. However, that does not mean that they are always sufficient. To set the right values, follow the instructions in Section 17.4, “Calculating crashkernel Allocation Size”.

Important
Important: After Hardware Changes, Set Kdump Memory Values Again

If you have set up Kdump on a computer and later decide to change the amount of RAM or hard disks available to it, YaST will continue to display and use outdated memory values.

To work around this, determine the necessary memory again, as described in Section 17.4, “Calculating crashkernel Allocation Size”. Then set it manually in YaST.

Click Dump Filtering in the left pane, and check what pages to include in the dump. You do not need to include the following memory content to be able to debug kernel problems:

  • Pages filled with zero

  • Cache pages

  • User data pages

  • Free pages

In the Dump Target window, select the type of the dump target and the URL where you want to save the dump. If you selected a network protocol, such as FTP or SSH, you need to enter relevant access information as well.

Tip
Tip: Sharing the Dump Directory with Other Applications

It is possible to specify a path for saving Kdump dumps where other applications also save their dumps. When cleaning its old dump files, Kdump will safely ignore other applications' dump files.

Fill the Email Notification window information if you want Kdump to inform you about its events via e-mail and confirm your changes with OK after fine tuning Kdump in the Expert Settings window. Kdump is now configured.

17.8 Analyzing the Crash Dump

After you obtain the dump, it is time to analyze it. There are several options.

The original tool to analyze the dumps is GDB. You can even use it in the latest environments, although it has several disadvantages and limitations:

  • GDB was not specifically designed to debug kernel dumps.

  • GDB does not support ELF64 binaries on 32-bit platforms.

  • GDB does not understand other formats than ELF dumps (it cannot debug compressed dumps).

That is why the crash utility was implemented. It analyzes crash dumps and debugs the running system as well. It provides functionality specific to debugging the Linux kernel and is much more suitable for advanced debugging.

If you want to debug the Linux kernel, you need to install its debugging information package in addition. Check if the package is installed on your system with:

tux > zypper se kernel | grep debug
Important
Important: Repository for Packages with Debugging Information

If you subscribed your system for online updates, you can find debuginfo packages in the *-Debuginfo-Updates online installation repository relevant for SUSE Linux Enterprise Server 12 SP3. Use YaST to enable the repository.

To open the captured dump in crash on the machine that produced the dump, use a command like this:

crash /boot/vmlinux-2.6.32.8-0.1-default.gz \
/var/crash/2010-04-23-11\:17/vmcore

The first parameter represents the kernel image. The second parameter is the dump file captured by Kdump. You can find this file under /var/crash by default.

Tip
Tip: Getting Basic Information from a Kernel Crash Dump

SUSE Linux Enterprise Server ships with the utility kdumpid (included in a package with the same name) for identifying unknown kernel dumps. It can be used to extract basic information such as architecture and kernel release. It supports lkcd, diskdump, Kdump files and ELF dumps. When called with the -v switch it tries to extract additional information such as machine type, kernel banner string and kernel configuration flavor.

17.8.1 Kernel Binary Formats

The Linux kernel comes in Executable and Linkable Format (ELF). This file is usually called vmlinux and is directly generated in the compilation process. Not all boot loaders support ELF binaries, especially on the AMD64/Intel 64 architecture. The following solutions exist on different architectures supported by SUSE® Linux Enterprise Server.

17.8.1.1 AMD64/Intel 64

Kernel packages for AMD64/Intel 64 from SUSE contain two kernel files: vmlinuz and vmlinux.gz.

  • vmlinuz This is the file executed by the boot loader.

    The Linux kernel consists of two parts: the kernel itself (vmlinux) and the setup code run by the boot loader. These two parts are linked together to create vmlinuz (note the distinction: z compared to x).

    In the kernel source tree, the file is called bzImage.

  • vmlinux.gz This is a compressed ELF image that can be used by crash and GDB. The ELF image is never used by the boot loader itself on AMD64/Intel 64. Therefore, only a compressed version is shipped.

17.8.1.2 POWER

The yaboot boot loader on POWER also supports loading ELF images, but not compressed ones. In the POWER kernel package, there is an ELF Linux kernel file vmlinux. Considering crash, this is the easiest architecture.

If you decide to analyze the dump on another machine, you must check both the architecture of the computer and the files necessary for debugging.

You can analyze the dump on another computer only if it runs a Linux system of the same architecture. To check the compatibility, use the command uname -i on both computers and compare the outputs.

If you are going to analyze the dump on another computer, you also need the appropriate files from the kernel and kernel debug packages.

  1. Put the kernel dump, the kernel image from /boot, and its associated debugging info file from /usr/lib/debug/boot into a single empty directory.

  2. Additionally, copy the kernel modules from /lib/modules/$(uname -r)/kernel/ and the associated debug info files from /usr/lib/debug/lib/modules/$(uname -r)/kernel/ into a subdirectory named modules.

  3. In the directory with the dump, the kernel image, its debug info file, and the modules subdirectory, start the crash utility:

    tux > crash VMLINUX-VERSION vmcore

Regardless of the computer on which you analyze the dump, the crash utility will produce output similar to this:

tux > crash /boot/vmlinux-2.6.32.8-0.1-default.gz \
/var/crash/2010-04-23-11\:17/vmcore

crash 4.0-7.6
Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008  Red Hat, Inc.
Copyright (C) 2004, 2005, 2006  IBM Corporation
Copyright (C) 1999-2006  Hewlett-Packard Co
Copyright (C) 2005, 2006  Fujitsu Limited
Copyright (C) 2006, 2007  VA Linux Systems Japan K.K.
Copyright (C) 2005  NEC Corporation
Copyright (C) 1999, 2002, 2007  Silicon Graphics, Inc.
Copyright (C) 1999, 2000, 2001, 2002  Mission Critical Linux, Inc.
This program is free software, covered by the GNU General Public License,
and you are welcome to change it and/or distribute copies of it under
certain conditions.  Enter "help copying" to see the conditions.
This program has absolutely no warranty.  Enter "help warranty" for details.

GNU gdb 6.1
Copyright 2004 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "x86_64-unknown-linux-gnu"...

      KERNEL: /boot/vmlinux-2.6.32.8-0.1-default.gz
   DEBUGINFO: /usr/lib/debug/boot/vmlinux-2.6.32.8-0.1-default.debug
    DUMPFILE: /var/crash/2009-04-23-11:17/vmcore
        CPUS: 2
        DATE: Thu Apr 23 13:17:01 2010
      UPTIME: 00:10:41
LOAD AVERAGE: 0.01, 0.09, 0.09
       TASKS: 42
    NODENAME: eros
     RELEASE: 2.6.32.8-0.1-default
     VERSION: #1 SMP 2010-03-31 14:50:44 +0200
     MACHINE: x86_64  (2999 Mhz)
      MEMORY: 1 GB
       PANIC: "SysRq : Trigger a crashdump"
         PID: 9446
     COMMAND: "bash"
        TASK: ffff88003a57c3c0  [THREAD_INFO: ffff880037168000]
         CPU: 1
       STATE: TASK_RUNNING (SYSRQ)
crash> 

The command output prints first useful data: There were 42 tasks running at the moment of the kernel crash. The cause of the crash was a SysRq trigger invoked by the task with PID 9446. It was a Bash process because the echo that has been used is an internal command of the Bash shell.

The crash utility builds upon GDB and provides many additional commands. If you enter bt without any parameters, the backtrace of the task running at the moment of the crash is printed:

crash> bt
PID: 9446   TASK: ffff88003a57c3c0  CPU: 1   COMMAND: "bash"
 #0 [ffff880037169db0] crash_kexec at ffffffff80268fd6
 #1 [ffff880037169e80] __handle_sysrq at ffffffff803d50ed
 #2 [ffff880037169ec0] write_sysrq_trigger at ffffffff802f6fc5
 #3 [ffff880037169ed0] proc_reg_write at ffffffff802f068b
 #4 [ffff880037169f10] vfs_write at ffffffff802b1aba
 #5 [ffff880037169f40] sys_write at ffffffff802b1c1f
 #6 [ffff880037169f80] system_call_fastpath at ffffffff8020bfbb
    RIP: 00007fa958991f60  RSP: 00007fff61330390  RFLAGS: 00010246
    RAX: 0000000000000001  RBX: ffffffff8020bfbb  RCX: 0000000000000001
    RDX: 0000000000000002  RSI: 00007fa959284000  RDI: 0000000000000001
    RBP: 0000000000000002   R8: 00007fa9592516f0   R9: 00007fa958c209c0
    R10: 00007fa958c209c0  R11: 0000000000000246  R12: 00007fa958c1f780
    R13: 00007fa959284000  R14: 0000000000000002  R15: 00000000595569d0
    ORIG_RAX: 0000000000000001  CS: 0033  SS: 002b
crash> 

Now it is clear what happened: The internal echo command of Bash shell sent a character to /proc/sysrq-trigger. After the corresponding handler recognized this character, it invoked the crash_kexec() function. This function called panic() and Kdump saved a dump.

In addition to the basic GDB commands and the extended version of bt, the crash utility defines other commands related to the structure of the Linux kernel. These commands understand the internal data structures of the Linux kernel and present their contents in a human readable format. For example, you can list the tasks running at the moment of the crash with ps. With sym, you can list all the kernel symbols with the corresponding addresses, or inquire an individual symbol for its value. With files, you can display all the open file descriptors of a process. With kmem, you can display details about the kernel memory usage. With vm, you can inspect the virtual memory of a process, even at the level of individual page mappings. The list of useful commands is very long and many of these accept a wide range of options.

The commands that we mentioned reflect the functionality of the common Linux commands, such as ps and lsof. To find out the exact sequence of events with the debugger, you need to know how to use GDB and to have strong debugging skills. Both of these are out of the scope of this document. In addition, you need to understand the Linux kernel. Several useful reference information sources are given at the end of this document.

17.9 Advanced Kdump Configuration

The configuration for Kdump is stored in /etc/sysconfig/kdump. You can also use YaST to configure it. Kdump configuration options are available under System › Kernel Kdump in YaST Control Center. The following Kdump options may be useful for you.

You can change the directory for the kernel dumps with the KDUMP_SAVEDIR option. Keep in mind that the size of kernel dumps can be very large. Kdump will refuse to save the dump if the free disk space, subtracted by the estimated dump size, drops below the value specified by the KDUMP_FREE_DISK_SIZE option. Note that KDUMP_SAVEDIR understands the URL format PROTOCOL://SPECIFICATION, where PROTOCOL is one of file, ftp, sftp, nfs or cifs, and specification varies for each protocol. For example, to save kernel dump on an FTP server, use the following URL as a template: ftp://username:password@ftp.example.com:123/var/crash.

Kernel dumps are usually huge and contain many pages that are not necessary for analysis. With KDUMP_DUMPLEVEL option, you can omit such pages. The option understands numeric value between 0 and 31. If you specify 0, the dump size will be largest. If you specify 31, it will produce the smallest dump. For a complete table of possible values, see the manual page of kdump (man 7 kdump).

Sometimes it is very useful to make the size of the kernel dump smaller. For example, if you want to transfer the dump over the network, or if you need to save some disk space in the dump directory. This can be done with KDUMP_DUMPFORMAT set to compressed. The crash utility supports dynamic decompression of the compressed dumps.

Important
Important: Changes to the Kdump Configuration File

You always need to execute systemctl restart kdump after you make manual changes to /etc/sysconfig/kdump. Otherwise, these changes will take effect next time you reboot the system.

17.10 For More Information

There is no single comprehensive reference to Kexec and Kdump usage. However, there are helpful resources that deal with certain aspects:

For more details on crash dump analysis and debugging tools, use the following resources:

  • In addition to the info page of GDB (info gdb), there are printable guides at http://sourceware.org/gdb/documentation/ .

  • A white paper with a comprehensive description of the crash utility usage can be found at http://people.redhat.com/anderson/crash_whitepaper/.

  • The crash utility also features a comprehensive online help. Use help COMMAND to display the online help for command.

  • If you have the necessary Perl skills, you can use Alicia to make the debugging easier. This Perl-based front-end to the crash utility can be found at http://alicia.sourceforge.net/ .

  • If you prefer to use Python instead, you should install Pykdump. This package helps you control GDB through Python scripts and can be downloaded from http://sf.net/projects/pykdump .

  • A very comprehensive overview of the Linux kernel internals is given in Understanding the Linux Kernel by Daniel P. Bovet and Marco Cesati (ISBN 978-0-596-00565-8).

Part VII Synchronized Clocks with Precision Time Protocol

18 Precision Time Protocol

For network environments, it is vital to keep the computer and other devices' clocks synchronized and accurate. There are several solutions to achieve this, for example the widely used Network Time Protocol (NTP) described in Chapter 24, Time Synchronization with NTP.

18 Precision Time Protocol

  • Filename: tuning_ptp.xml
  • ID: cha.tuning.ptp

For network environments, it is vital to keep the computer and other devices' clocks synchronized and accurate. There are several solutions to achieve this, for example the widely used Network Time Protocol (NTP) described in Chapter 24, Time Synchronization with NTP.

The Precision Time Protocol (PTP) is a protocol capable of sub-microsecond accuracy, which is better than what NTP achieves. PTP support is divided between the kernel and user space. The kernel in SUSE Linux Enterprise Server includes support for PTP clocks, which are provided by network drivers.

18.1 Introduction to PTP

The clocks managed by PTP follow a master-slave hierarchy. The slaves are synchronized to their masters. The hierarchy is updated by the best master clock (BMC) algorithm, which runs on every clock. The clock with only one port can be either master or slave. Such a clock is called an ordinary clock (OC). A clock with multiple ports can be master on one port and slave on another. Such a clock is called a boundary clock (BC). The top-level master is called the grandmaster clock. The grandmaster clock can be synchronized with a Global Positioning System (GPS). This way disparate networks can be synchronized with a high degree of accuracy.

The hardware support is the main advantage of PTP. It is supported by various network switches and network interface controllers (NIC). While it is possible to use non-PTP enabled hardware within the network, having network components between all PTP clocks PTP hardware enabled achieves the best possible accuracy.

18.1.1 PTP Linux Implementation

On SUSE Linux Enterprise Server, the implementation of PTP is provided by the linuxptp package. Install it with zypper install linuxptp. It includes the ptp4l and phc2sys programs for clock synchronization. ptp4l implements the PTP boundary clock and ordinary clock. When hardware time stamping is enabled, ptp4l synchronizes the PTP hardware clock to the master clock. With software time stamping, it synchronizes the system clock to the master clock. phc2sys is needed only with hardware time stamping to synchronize the system clock to the PTP hardware clock on the network interface card (NIC).

18.2 Using PTP

18.2.1 Network Driver and Hardware Support

PTP requires that the used kernel network driver supports either software or hardware time stamping. Moreover, the NIC must support time stamping in the physical hardware. You can verify the driver and NIC time stamping capabilities with ethtool:

ethtool -T eth0
Time stamping parameters for eth0:
Capabilities:
hardware-transmit     (SOF_TIMESTAMPING_TX_HARDWARE)
        software-transmit     (SOF_TIMESTAMPING_TX_SOFTWARE)
        hardware-receive      (SOF_TIMESTAMPING_RX_HARDWARE)
        software-receive      (SOF_TIMESTAMPING_RX_SOFTWARE)
        software-system-clock (SOF_TIMESTAMPING_SOFTWARE)
        hardware-raw-clock    (SOF_TIMESTAMPING_RAW_HARDWARE)
PTP Hardware Clock: 0
Hardware Transmit Timestamp Modes:
        off                   (HWTSTAMP_TX_OFF)
        on                    (HWTSTAMP_TX_ON)
Hardware Receive Filter Modes:
        none                  (HWTSTAMP_FILTER_NONE)
        all                   (HWTSTAMP_FILTER_ALL)

Software time stamping requires the following parameters:

SOF_TIMESTAMPING_SOFTWARE
SOF_TIMESTAMPING_TX_SOFTWARE
SOF_TIMESTAMPING_RX_SOFTWARE

Hardware time stamping requires the following parameters:

SOF_TIMESTAMPING_RAW_HARDWARE
SOF_TIMESTAMPING_TX_HARDWARE
SOF_TIMESTAMPING_RX_HARDWARE

18.2.2 Using ptp4l

ptp4l uses hardware time stamping by default. As root, you need to specify the network interface capable of hardware time stamping with the -i option. The -m tells ptp4l to print its output to the standard output instead of the system's logging facility:

ptp4l -m -i eth0
selected eth0 as PTP clock
port 1: INITIALIZING to LISTENING on INITIALIZE
port 0: INITIALIZING to LISTENING on INITIALIZE
port 1: new foreign master 00a152.fffe.0b334d-1
selected best master clock 00a152.fffe.0b334d
port 1: LISTENING to UNCALIBRATED on RS_SLAVE
master offset -25937 s0 freq +0 path delay       12340
master offset -27887 s0 freq +0 path delay       14232
master offset -38802 s0 freq +0 path delay       13847
master offset -36205 s1 freq +0 path delay       10623
master offset  -6975 s2 freq -30575 path delay   10286
port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
master offset  -4284 s2 freq -30135 path delay    9892

The master offset value represents the measured offset from the master (in nanoseconds).

The s0, s1, s2 indicators show the different states of the clock servo: s0 is unlocked, s1 is clock step, and s2 is locked. If the servo is in the locked state (s2), the clock will not be stepped (only slowly adjusted) if the pi_offset_const option is set to a negative value in the configuration file (see man 8 ptp4l for more information).

The freq value represents the frequency adjustment of the clock (in parts per billion, ppb).

The path delay value represents the estimated delay of the synchronization messages sent from the master (in nanoseconds).

Port 0 is a Unix domain socket used for local PTP management. Port 1 is the eth0 interface.

INITIALIZING, LISTENING, UNCALIBRATED and SLAVE are examples of port states which change on INITIALIZE, RS_SLAVE, and MASTER_CLOCK_SELECTED events. When the port state changes from UNCALIBRATED to SLAVE, the computer has successfully synchronized with a PTP master clock.

You can enable software time stamping with the -S option.

ptp4l -m -S -i eth3

You can also run ptp4l as a service:

systemctl start ptp4l

In this case, ptp4l reads its options from the /etc/sysconfig/ptp4l file. By default, this file tells ptp4l to read the configuration options from /etc/ptp4l.conf. For more information on ptp4l options and the configuration file settings, see man 8 ptp4l.

To enable the ptp4l service permanently, run the following:

systemctl enable ptp4l

To disable it, run

systemctl disable ptp4l

18.2.3 ptp4l Configuration File

ptp4l can read its configuration from an optional configuration file. As no configuration file is used by default, you need to specify it with -f.

ptp4l -f /etc/ptp4l.conf

The configuration file is divided into sections. The global section (indicated as [global]) sets the program options, clock options and default port options. Other sections are port specific, and they override the default port options. The name of the section is the name of the configured port—for example, [eth0]. An empty port section can be used to replace the command line option.

[global]
verbose               1
time_stamping         software
[eth0]

The example configuration file is an equivalent of the following command's options:

ptp4l -i eth0 -m -S

For a complete list of ptp4l configuration options, see man 8 ptp4l.

18.2.4 Delay Measurement

ptp4l measures time delay in two different ways: peer-to-peer (P2P) or end-to-end (E2E).

P2P

This method is specified with -P.

It reacts to changes in the network environment faster and is more accurate in measuring the delay. It is only used in networks where each port exchanges PTP messages with one other port. P2P needs to be supported by all hardware on the communication path.

E2E

This method is specified with -E. This is the default.

Automatic method selection

This method is specified with -A. The automatic option starts ptp4l in E2E mode, and changes to P2P mode if a peer delay request is received.

Important
Important: Common Measurement Method

All clocks on a single PTP communication path must use the same method to measure the time delay. A warning will be printed if either a peer delay request is received on a port using the E2E mechanism, or an E2E delay request is received on a port using the P2P mechanism.

18.2.5 PTP Management Client: pmc

You can use the pmc client to obtain more detailed information about ptp41. It reads from the standard input—or from the command line—actions specified by name and management ID. Then it sends the actions over the selected transport, and prints any received replies. There are three actions supported: GET retrieves the specified information, SET updates the specified information, and CMD (or COMMAND) initiates the specified event.

By default, the management commands are addressed to all ports. The TARGET command can be used to select a particular clock and port for the subsequent messages. For a complete list of management IDs, run pmc help.

pmc -u -b 0 'GET TIME_STATUS_NP'
sending: GET TIME_STATUS_NP
        90f2ca.fffe.20d7e9-0 seq 0 RESPONSE MANAGMENT TIME_STATUS_NP
                master_offset              283
                ingress_time               1361569379345936841
                cumulativeScaledRateOffset   +1.000000000
                scaledLastGmPhaseChange    0
                gmTimeBaseIndicator        0
                lastGmPhaseChange          0x0000'0000000000000000.0000
                gmPresent                  true
                gmIdentity                 00b058.feef.0b448a

The -b option specifies the boundary hops value in sent messages. Setting it to zero limits the boundary to the local ptp4l instance. Increasing the value will retrieve the messages also from PTP nodes that are further from the local instance. The returned information may include:

stepsRemoved

The number of communication nodes to the grandmaster clock.

offsetFromMaster, master_offset

The last measured offset of the clock from the master clock (nanoseconds).

meanPathDelay

The estimated delay of the synchronization messages sent from the master clock (nanoseconds).

gmPresent

If true, the PTP clock is synchronized to the master clock; the local clock is not the grandmaster clock.

gmIdentity

This is the grandmaster's identity.

For a complete list of pmc command line options, see man 8 pmc.

18.3 Synchronizing the Clocks with phc2sys

Use phc2sys to synchronize the system clock to the PTP hardware clock (PHC) on the network card. The system clock is considered a slave, while the network card a master. PHC itself is synchronized with ptp4l (see Section 18.2, “Using PTP”). Use -s to specify the master clock by device or network interface. Use -w to wait until ptp4l is in a synchronized state.

phc2sys -s eth0 -w

PTP operates in International Atomic Time (TAI), while the system clock uses Coordinated Universal Time (UTC). If you do not specify -w to wait for ptp4l synchronization, you can specify the offset in seconds between TAI and UTC with -O:

phc2sys -s eth0 -O -35

You can run phc2sys as a service as well:

systemctl start phc2sys

In this case, phc2sys reads its options from the /etc/sysconfig/phc2sys file. For more information on phc2sys options, see man 8 phc2sys.

To enable the phc2sys service permanently, run the following:

systemctl enable phc2sys

To disable it, run

systemctl dosable phc2sys

18.3.1 Verifying Time Synchronization

When PTP time synchronization is working properly and hardware time stamping is used, ptp4l and phc2sys output messages with time offsets and frequency adjustments periodically to the system log.

An example of the ptp4l output:

ptp4l[351.358]: selected /dev/ptp0 as PTP clock
ptp4l[352.361]: port 1: INITIALIZING to LISTENING on INITIALIZE
ptp4l[352.361]: port 0: INITIALIZING to LISTENING on INITIALIZE
ptp4l[353.210]: port 1: new foreign master 00a069.eefe.0b442d-1
ptp4l[357.214]: selected best master clock 00a069.eefe.0b662d
ptp4l[357.214]: port 1: LISTENING to UNCALIBRATED on RS_SLAVE
ptp4l[359.224]: master offset       3304 s0 freq      +0 path delay      9202
ptp4l[360.224]: master offset       3708 s1 freq  -28492 path delay      9202
ptp4l[361.224]: master offset      -3145 s2 freq  -32637 path delay      9202
ptp4l[361.224]: port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
ptp4l[362.223]: master offset       -145 s2 freq  -30580 path delay      9202
ptp4l[363.223]: master offset       1043 s2 freq  -28436 path delay      8972
[...]
ptp4l[371.235]: master offset        285 s2 freq  -28511 path delay      9199
ptp4l[372.235]: master offset        -78 s2 freq  -28788 path delay      9204

An example of the phc2sys output:

phc2sys[616.617]: Waiting for ptp4l...
phc2sys[628.628]: phc offset     66341 s0 freq      +0 delay   2729
phc2sys[629.628]: phc offset     64668 s1 freq  -37690 delay   2726
[...]
phc2sys[646.630]: phc offset      -333 s2 freq  -37426 delay   2747
phc2sys[646.630]: phc offset       194 s2 freq  -36999 delay   2749

ptp4l normally writes messages very frequently. You can reduce the frequency with the summary_interval directive. Its value is an exponent of the 2^N expression. For example, to reduce the output to every 1024 (which is equal to 2^10) seconds, add the following line to the /etc/ptp4l.conf file:

summary_interval 10

You can also reduce the frequency of the phc2sys command's updates with the -u SUMMARY-UPDATES option.

18.4 Examples of Configurations

This section includes several examples of ptp4l configuration. The examples are not full configuration files but rather a minimal list of changes to be made to the specific files. The string ethX stands for the actual network interface name in your setup.

Example 18.1: Slave clock using software time stamping

/etc/sysconfig/ptp4l:

OPTIONS=”-f /etc/ptp4l.conf -i ethX”

No changes made to the distribution /etc/ptp4l.conf.

Example 18.2: Slave clock using hardware time stamping

/etc/sysconfig/ptp4l:

OPTIONS=”-f /etc/ptp4l.conf -i ethX”

/etc/sysconfig/phc2sys:

OPTIONS=”-s ethX -w”

No changes made to the distribution /etc/ptp4l.conf.

Example 18.3: Master clock using hardware time stamping

/etc/sysconfig/ptp4l:

OPTIONS=”-f /etc/ptp4l.conf -i ethX”

/etc/sysconfig/phc2sys:

OPTIONS=”-s CLOCK_REALTIME -c ethX -w”

/etc/ptp4l.conf:

priority1 127
Example 18.4: Master clock using software time stamping (not generally recommended)

/etc/sysconfig/ptp4l:

OPTIONS=”-f /etc/ptp4l.conf -i ethX”

/etc/ptp4l.conf:

priority1 127

18.5 PTP and NTP

NTP and PTP time synchronization tools can coexist, synchronizing time from one to another in both directions.

18.5.1 NTP to PTP Synchronization

When ntpd is used to synchronize the local system clock, you can configure the ptp4l to be the grandmaster clock distributing the time from the local system clock via PTP. Include the priority1 option in /etc/ptp4l.conf:

[global]
priority1 127
[eth0]

Then run ptp4l:

ptp4l -f /etc/ptp4l.conf

When hardware time stamping is used, you need to synchronize the PTP hardware clock to the system clock with phc2sys:

phc2sys -c eth0 -s CLOCK_REALTIME -w

18.5.2 PTP to NTP Synchronization

You can configure ntpd to distribute the time from the system clock synchronized by ptp4l or phc2sys by using the local reference clock driver. Moreover, you need to stop ntpd from adjusting the system clock—do not specify any remote NTP servers in /etc/ntp.conf:

server   127.127.1.0
fudge    127.127.1.0 stratum 0
Note
Note: NTP and DHCP

When the DHCP client command dhclient receives a list of NTP servers, it adds them to NTP configuration by default. To prevent this behavior, set

NETCONFIG_NTP_POLICY=""

in the /etc/sysconfig/network/config file.

A Documentation Updates

  • Filename: tuning_docupdates.xml
  • ID: app.tuning.docupdates

This chapter lists content changes for this document.

This manual was updated on the following dates:

A.1 December 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)

General

A.2 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)

General

A.3 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)

General
  • The e-mail address for documentation feedback has changed to doc-team@suse.com.

  • The documentation for Docker has been enhanced and renamed to Docker Guide.

Chapter 2, System Monitoring Utilities
Chapter 3, Analyzing and Managing System Log Files
  • Removed references to faillog, which is no longer shipped with SUSE Linux Enterprise Server.

Chapter 4, SystemTap—Filtering and Analyzing System Data
Bugfixes

A.4 March 2016 (Maintenance Release of SUSE Linux Enterprise Server 12 SP1)

A.5 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)

General
  • SMT Guide is now part of the documentation for SUSE Linux Enterprise Server.

  • Add-ons provided by SUSE have been renamed as modules and extensions. The manuals have been updated to reflect this change.

  • Numerous small fixes and additions to the documentation, based on technical feedback.

  • The registration service has been changed from Novell Customer Center to SUSE Customer Center.

  • In YaST, you will now reach Network Settings via the System group. Network Devices is gone (https://bugzilla.suse.com/show_bug.cgi?id=867809).

Chapter 2, System Monitoring Utilities
Chapter 6, Hardware-Based Performance Monitoring with Perf
  • Added Perf chapter, including introductory information about Instruction-Based Sampling (IBS) (Fate #315868).

Chapter 18, Precision Time Protocol
  • Added PTP chapter (Fate #316795).

Bugfixes

A.6 February 2015 (Documentation Maintenance Update)

Bugfixes

A.7 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)

General
  • Removed all KDE documentation and references because KDE is no longer shipped.

  • Removed all references to SuSEconfig, which is no longer supported (Fate #100011).

  • Move from System V init to systemd (Fate #310421). Updated affected parts of the documentation.

  • YaST Runlevel Editor has changed to Services Manager (Fate #312568). Updated affected parts of the documentation.

  • Removed all references to ISDN support, as ISDN support has been removed (Fate #314594).

  • Removed all references to the YaST DSL module as it is no longer shipped (Fate #316264).

  • Removed all references to the YaST Modem module as it is no longer shipped (Fate #316264).

  • Btrfs has become the default file system for the root partition (Fate #315901). Updated affected parts of the documentation.

  • The dmesg now provides human-readable time stamps in ctime()-like format (Fate #316056). Updated affected parts of the documentation.

  • syslog and syslog-ng have been replaced by rsyslog (Fate #316175). Updated affected parts of the documentation.

  • MariaDB is now shipped as the relational database instead of MySQL (Fate #313595). Updated affected parts of the documentation.

  • SUSE-related products are no longer available from http://download.novell.com but from http://download.suse.com. Adjusted links accordingly.

  • Novell Customer Center has been replaced with SUSE Customer Center. Updated affected parts of the documentation.

  • /var/run is mounted as tmpfs (Fate #303793). Updated affected parts of the documentation.

  • The following architectures are no longer supported: IA64 and x86. Updated affected parts of the documentation.

  • The traditional method for setting up the network with ifconfig has been replaced by wicked. Updated affected parts of the documentation.

  • A lot of networking commands are deprecated and have been replaced by newer commands (usually ip). Updated affected parts of the documentation.

    arp: ip neighbor
    ifconfig: ip addr, ip link
    iptunnel: ip tunnel
    iwconfig: iw
    nameif: ip link, ifrename
    netstat: ss, ip route, ip -s link, ip maddr
    route: ip route
  • Numerous small fixes and additions to the documentation, based on technical feedback.

Chapter 2, System Monitoring Utilities
Chapter 4, SystemTap—Filtering and Analyzing System Data

Added a link to the example scripts Web page to Section 4.1.1, “SystemTap Scripts”.

Chapter 7, OProfile—System-Wide Profiler

Corrected statements on the effects of sampling rates in Section 7.4.2, “Getting Event Configurations”.

Chapter 10, Automatic Non-Uniform Memory Access (NUMA) Balancing

New chapter.

Chapter 13, Tuning the Task Scheduler
Chapter 14, Tuning the Memory Management Subsystem

Added detailed descriptions on tunable parameters to Section 14.3.2, “Writeback Parameters”.

Chapter 17, Kexec and Kdump
Obsolete Content
  • Chapter Monitoring with Nagios has been removed from Part II, “System Monitoring” (Fate #316136), because Nagios is no longer shipped on SUSE Linux Enterprise 12.

  • Chapter Perf mon2—Hardware-Based Performance Monitoring has been removed from Part III, “Kernel Monitoring”, because perfmon2 is no longer shipped on SUSE Linux Enterprise 12.

Bugfixes
SUSE Linux Enterprise Server 12 SP3

Subscription Management Tool for SLES 12 SP3

Authors: Tomáš Bažant, Jakub Friedl, and Florian Nadge
Publication Date: April 04, 2018
About This Guide
Overview
Additional Documentation and Resources
Feedback
Documentation Conventions
1 SMT Installation
1.1 SMT Configuration Wizard
1.2 Upgrading from Previous Versions of SMT
1.3 Enabling SLP Announcements
2 SMT Server Configuration
2.1 Activating and Deactivating SMT with YaST
2.2 Setting the Update Server Credentials with YaST
2.3 Setting SMT Database Password with YaST
2.4 Setting E-mail Addresses to Receive Reports with YaST
2.5 Setting the SMT Job Schedule with YaST
3 Mirroring Repositories on the SMT Server
3.1 Mirroring Credentials
3.2 Managing Software Repositories with SMT Command Line Tools
3.3 The Structure of /srv/www/htdocs for SLE 11
3.4 The Structure of /srv/www/htdocs for SLE 12
3.5 Using the Test Environment
3.6 Testing and Filtering Update Repositories with Staging
3.7 Repository Preloading
4 Managing Repositories with YaST SMT Server Management
4.1 Starting SMT Management Module
4.2 Viewing and Managing Repositories
4.3 Staging Repositories
4.4 Jobs and Client Status Monitoring
5 Managing Client Machines with SMT
5.1 Listing Registered Clients
5.2 Deleting Registrations
5.3 Manual Registration of Clients at SUSE Customer Center
5.4 Scheduling Periodic Registrations of Clients at SUSE Customer Center
5.5 Compliance Monitoring
6 SMT Reports
6.1 Report Schedule and Recipients
6.2 Report Output Formats and Targets
7 SMT Tools and Configuration Files
7.1 Important Scripts and Tools
7.2 SMT Configuration Files
7.3 Server Certificates
8 Configuring Clients to Use SMT
8.1 Using Kernel Parameters to Access an SMT Server
8.2 Configuring Clients with AutoYaST Profile
8.3 Configuring Clients with the clientSetup4SMT.sh Script in SLE 11 and 12
8.4 Configuring Clients with YaST
8.5 Registering SLE11 Clients against SMT Test Environment
8.6 Registering SLE12 Clients against SMT Test Environment
8.7 Listing Accessible Repositories
8.8 Online Migration of SUSE Linux Enterprise Clients
8.9 How to Update Red Hat Enterprise Linux with SMT
9 Advanced Topics
9.1 Backup of the SMT Server
9.2 Disconnected SMT Servers
A SMT REST API
B Documentation Updates
B.1 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)
B.2 April 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP2)
B.3 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)
B.4 March 2016 (Maintenance Release of SUSE Linux Enterprise Server 12 SP1)
B.5 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)

Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

About This Guide

  • Filename: smt_overview.xml
  • ID: pre_smt

Subscription Management Tool (SMT) for SUSE Linux Enterprise 12 SP3 allows enterprise customers to optimize the management of SUSE Linux Enterprise software updates and subscription entitlements. It establishes a proxy system for SUSE® Customer Center with repository (formerly known as catalog) and registration targets. This helps you centrally manage software updates within the firewall on a per-system basis, while maintaining your corporate security policies and regulatory compliance.

SMT allows you to provision updates for all of your devices running a product based on SUSE Linux Enterprise. By downloading these updates once and distributing them throughout the enterprise, you can set more restrictive firewall policies. This also reduces bandwidth usage, as there is no need to download the same updates for each device. SMT is fully supported and available as a download for customers with an active SUSE Linux Enterprise product subscription.

Subscription Management Tool provides functionality that can be useful in many situations, including the following:

  • You want to update both SUSE Linux Enterprise and RedHat Enterprise Linux servers.

  • You want to get a detailed overview of your company's license compliance.

  • Not all machines in your environment can be connected to SUSE Customer Center to register and retrieve updates for bandwidth or security reasons.

  • There are SUSE Linux Enterprise hosts that are restricted and difficult to update without putting in place a custom update management solution.

  • You need to integrate additional software update external or internal repositories into your update solution.

  • You are looking for a turnkey box staging solution for testing updates before releasing them to the clients.

  • You want to have a quick overview of the patch status of your SUSE Linux Enterprise servers and desktops.

SMT
Figure 1: SMT

1 Overview

The Subscription Management Tool Guide is divided into the following chapters:

SMT Installation

Introduction to the SMT installation process and the SMT Configuration Wizard. You will learn how to install the SMT add-on on your base system during the installation process or on an already installed base system.

SMT Server Configuration

Description of the YaST configuration module SMT Server. This chapter explains how to set and configure organization credentials, SMT database passwords, and e-mail addresses to send SMT reports, or set the SMT job schedule, and activate or deactivate the SMT service.

Mirroring Repositories on the SMT Server

Explanation of how to mirror the installation and update sources with YaST.

Managing Repositories with YaST SMT Server Management

Description of how to register client machines on SUSE Customer Center. The client machines must be configured to use SMT.

SMT Reports

In-depth look at generated reports based on SMT data. Generated reports contain statistics of all registered machines and products used and of all active, expiring, or missing subscriptions.

SMT Tools and Configuration Files

Description of the most important scripts, configuration files and certificates supplied with SMT.

Configuring Clients to Use SMT

Introduction to configuring any client machine to register against SMT and download software updates from there instead of communicating directly with the SUSE Customer Center.

2 Additional Documentation and Resources

Chapters in this manual contain links to additional documentation resources that are available either on the system or on the Internet.

For an overview of the documentation available for your product and the latest documentation updates, refer to http://www.suse.com/documentation.

3 Feedback

  • Filename: common_intro_feedback_i.xml
  • ID: no ID found

Several feedback channels are available:

Bugs and Enhancement Requests

For services and support options available for your product, refer to http://www.suse.com/support/.

Help for openSUSE is provided by the community. Refer to https://en.opensuse.org/Portal:Support for more information.

To report bugs for a product component, go to https://scc.suse.com/support/requests, log in, and click Create New.

User Comments

We want to hear your comments about and suggestions for this manual and the other documentation included with this product. Use the User Comments feature at the bottom of each page in the online documentation or go to http://www.suse.com/documentation/feedback.html and enter your comments there.

Mail

For feedback on the documentation of this product, you can also send a mail to doc-team@suse.com. Make sure to include the document title, the product version and the publication date of the documentation. To report errors or suggest enhancements, provide a concise description of the problem and refer to the respective section number and page (or URL).

4 Documentation Conventions

  • Filename: common_intro_typografie_i.xml
  • ID: no ID found

The following notices and typographical conventions are used in this documentation:

  • /etc/passwd: directory names and file names

  • PLACEHOLDER: replace PLACEHOLDER with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • package name : name of a package

  • Alt, AltF1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File › Save As: menu items, buttons

  • x86_64 This paragraph is only relevant for the AMD64/Intel 64 architecture. The arrows mark the beginning and the end of the text block.

    System z, POWER This paragraph is only relevant for the architectures z Systems and POWER. The arrows mark the beginning and the end of the text block.

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

  • Commands that must be run with root privileges. Often you can also prefix these commands with the sudo command to run them as non-privileged user.

    root # command
    tux > sudo command
  • Commands that can be run by non-privileged users.

    tux > command
  • Notices

    Warning
    Warning: Warning Notice

    Vital information you must be aware of before proceeding. Warns you about security issues, potential loss of data, damage to hardware, or physical hazards.

    Important
    Important: Important Notice

    Important information you should be aware of before proceeding.

    Note
    Note: Note Notice

    Additional information, for example about differences in software versions.

    Tip
    Tip: Tip Notice

    Helpful information, like a guideline or a piece of practical advice.

1 SMT Installation

  • Filename: smt_install.xml
  • ID: smt.installation

SMT is included in SUSE Linux Enterprise Server starting with version 12 SP1. To install it, start SUSE Linux Enterprise Server installation, and click Software on the Installation Settings screen. Select the Subscription Management Tool pattern on the Software Selection and System Tasks screen, then click OK.

SMT Pattern
Figure 1.1: SMT Pattern
Tip
Tip: Installing SMT on an Existing System

To install SMT on the existing SUSE Linux Enterprise Server system, run YaST › Software › Software Management, select View › Patterns and select the SMT pattern there.

It is recommended to check for available SMT updates immediately after installing SUSE Linux Enterprise Server using the zypper patch command. SUSE continuously releases maintenance updates for SMT, and newer packages are likely to be available.

After the system is installed and updated, perform an initial SMT configuration using YaST › Network Services › SMT Configuration Wizard.

Note
Note: Install smt-client

The smt-client package needs to be installed on clients connected to the SMT server. The package requires no configuration, and it can be installed using the sudo zypper in smt-client command.

1.1 SMT Configuration Wizard

The two-step SMT Configuration Wizard helps you configure SMT after SUSE Linux Enterprise Server installation is finished. You can change the configuration later using the YaST SMT Server Configuration module—see Chapter 2, SMT Server Configuration.

  1. The Enable Subscription Management Tool service (SMT) option is enabled by default. Toggle it only if you want to disable the SMT product.

    If the firewall is enabled, enable Open Port in Firewall to allow access to the SMT service from remote computers.

    Enter your SUSE Customer Center organization credentials in User and Password. If you do not know your SUSE Customer Center credentials, refer to Section 3.1, “Mirroring Credentials”. Test the entered credentials using the Test button. SMT will connect to the Customer Center server using the provided credentials and download testing data.

    Enter the e-mail address you used for the SUSE Customer Center registration into SCC E-mail Used for Registration.

    Your SMT Server URL should contain the URL of the SMT server being configured. It is populated automatically.

    Click Next to continue to the second configuration step.

    SMT Wizard
    Figure 1.2: SMT Wizard
  2. For security reasons, SMT requires a separate user to connect to the database. In the Database Password for smt User screen, set the database password for this user.

    Enter all e-mail addresses for receiving SMT reports using the Add button. Use the Edit and Delete buttons to modify and delete the existing addresses. When you have done that, click Next.

  3. If the current database root password is empty, you will be prompted to specify it.

  4. By default, SMT is set to communicate with the client hosts via a secure protocol. For this, the server needs to have a server SSL certificate. The wizard displays a warning if the certificate does not exist. You can create a certificate using the Run CA Management button. Refer to Section 17.2, “YaST Modules for CA Management” for detailed information on managing certificates with YaST.

    Missing Server Certificate
    Figure 1.3: Missing Server Certificate

1.2 Upgrading from Previous Versions of SMT

This section provides information on upgrading SMT from the previous versions.

Important
Important: Upgrade from Versions Prior to 11 SP3

A direct upgrade path from SMT prior to version 11 SP3 is not supported. You need to do the following:

  1. Upgrade the operating system to SUSE Linux Enterprise Server 11 SP3 or SP4 as described in https://www.suse.com/documentation/sles11/book_sle_deployment/data/cha_update_sle.html

  2. At the same time upgrade SMT to version 11 SP3 as described in https://www.suse.com/documentation/smt11/book_yep/data/smt_installation_upgrade.html.

  3. Follow the steps described in Section 1.2.2, “Upgrade from SMT 11 SP3”.

1.2.1 Upgrade from SMT 12 SP1

Upgrade from SMT 12 SP1 is performed automatically during the SUSE Linux Enterprise Server upgrade and requires no additional manual steps. For more information on SUSE Linux Enterprise Server upgrade, see Chapter 19, Upgrading SUSE Linux Enterprise.

1.2.2 Upgrade from SMT 11 SP3

To upgrade SMT from version 11 SP3 to 12 SP2, follow the steps below.

  1. If you have not already done so, migrate from Novell Customer Center to SUSE Customer Center as described in Section 1.2.2.1, “Migration to SUSE Customer Center on SMT 11 SP3”.

  2. Back up and migrate the database. See the general procedure in Section 19.3.4, “Migrate your MySQL Database”.

  3. Upgrade to SUSE Linux Enterprise Server 12 SP2 as described in Chapter 19, Upgrading SUSE Linux Enterprise.

  4. Look if the new /etc/my.cnf.rpmnew exists and update it with any custom changes you need. Then copy it over the existing /etc/my.cnf:

    cp /etc/my.cnf.rpmnew /etc/my.cnf
  5. Enable the smt target to start at the system boot:

    systemctl enable smt.target

    Start it immediately, if necessary:

    systemctl start smt.target

1.2.2.1 Migration to SUSE Customer Center on SMT 11 SP3

Before upgrading to SUSE Linux Enterprise Server 12, you need to switch the registration center on SUSE Linux Enterprise Server 11. SMT now registers with SUSE Customer Center instead of Novell Customer Center. You can do this either via a YaST module or command line tools.

Before performing the switch between customer centers, make sure that the target customer center serves all products that are registered with SMT. Both YaST and the command line tools perform a check to find out whether all products can be served with the new registration server.

To perform the migration to SUSE Customer Center via command line, use the following command:

smt ncc-scc-migration

The migration itself takes time, and during the migration process the SMT server may not be able to serve clients that are already registered.

The migration process itself changes the registration server and the proper type of API in the configuration files. No further (configuration) changes are needed on the SMT.

To migrate from Novell Customer Center to SUSE Customer Center via YaST, use the YaST smt-server module.

When migration has been completed, it is necessary to synchronize SMT with the customer center. It is recommended to ensure that the repositories are up to date. This can be done using the following commands:

   smt sync
   smt mirror

1.3 Enabling SLP Announcements

SMT includes the SLP service description file (/etc/slp.reg.d/smt.reg). To enable SLP announcements of the SMT service, open respective ports in your firewall and enable the SLP service:

sysconf_addword /etc/sysconfig/SuSEfirewall2 FW_SERVICES_EXT_TCP "427"
sysconf_addword /etc/sysconfig/SuSEfirewall2 FW_SERVICES_EXT_UDP "427"
insserv slpd
rcslpd start

2 SMT Server Configuration

  • Filename: smt_server.xml
  • ID: smt.server

This chapter introduces the YaST configuration module for the SMT server. This module can be used to set and configure mirroring credentials, SMT database passwords, and e-mail addresses for receiving SMT reports. The module also lets you set the SMT job schedule, and activate or deactivate the SMT service.

To configure SMT with SMT Server Configuration, follow the steps below.

  1. Start the YaST module SMT Server Configuration from the YaST control center or by running yast smt-server from the command line.

  2. To activate SMT, toggle the Enable Subscription Management Tool Service (SMT) option in the Customer Center Access section. For more information about activating SMT with YaST, see Section 2.1, “Activating and Deactivating SMT with YaST”.

  3. If the firewall is enabled, activate Open Port in Firewall.

  4. In the Customer Center Configuration section of Customer Center Access, you can set the custom server URLs. Set and test credentials for the SUSE Update service. Correct credentials are necessary to enable mirroring from the download server and determine the products that should be mirrored. Also set the e-mail address used for the registration and the URL of your SMT server. For more information, see Section 2.2, “Setting the Update Server Credentials with YaST”.

  5. In the Database and Reporting section, set the password for the SMT user in the Maria DB database and specify e-mail addresses for receiving reports. For more information, see Section 2.3, “Setting SMT Database Password with YaST” and Section 2.4, “Setting E-mail Addresses to Receive Reports with YaST”.

  6. In the Scheduled SMT Jobs section, set a schedule for SMT jobs, such as synchronization of updates, SUSE Customer Center registration, and SMT report generation. For more information, see Section 2.5, “Setting the SMT Job Schedule with YaST”.

  7. When you are satisfied with the configuration, click OK. YaST updates the SMT configuration and starts or restarts necessary services.

    If you want to abort the configuration and cancel any changes, click Cancel.

    Note
    Note: Check for Certificate

    When the SMT Configuration applies changes, it checks whether the common server certificate exists. If the certificate does not exist, you will be asked whether the certificate should be created.

2.1 Activating and Deactivating SMT with YaST

YaST provides an easy way to activate or deactivate the SMT service. To activate SMT using YaST, follow the steps below.

  1. Switch to the Customer Center Access section in the SMT Configuration.

  2. Activate the Enable Subscription Management Tool service (SMT) option.

    Note
    Note: Organization Credentials

    Specify organization credentials before activating SMT. For more information on how to set organization credentials with YaST, see Section 2.2, “Setting the Update Server Credentials with YaST”.

  3. Click Finish to apply the changes and leave the SMT Configuration.

To deactivate SMT with YaST, proceed as follows.

  1. Switch to the Customer Center Access section in the SMT Configuration.

  2. Disable the Enable Subscription Management Tool service (SMT) option.

  3. Click Finish to apply the changes and leave the SMT Configuration.

When activating SMT, YaST performs the following actions.

  • The Apache configuration is changed by creating symbolic links in the /etc/apache2/conf.d/ directory. Links to the /etc/smt.d/nu_server.conf and /etc/smt.d/smt_mod_perl.conf files are created there.

  • The Apache Web server is started (or reloaded if already running).

  • The Maria DB server is started or restarted. The smt user and all necessary tables in the database are created, if needed.

  • The schema of the SMT database is checked. If the database schema is outdated, the SMT database is upgraded to the current schema.

  • Cron is updated by creating a symbolic link in the /etc/cron.d/ directory. A link to the /etc/smt.d/novell.com-smt file is created there.

When deactivating SMT, YaST performs the following actions.

  • Symbolic links that were created upon SMT activation in the /etc/apache2/conf.d/ and /etc/cron.d/ directories are deleted.

  • The Cron daemon, the Apache server, and the Maria DB database daemon are restarted. Neither Apache nor Maria DB are stopped, as they may be used for other purposes than the SMT service.

2.2 Setting the Update Server Credentials with YaST

The following procedure describes how to set and test the download server credentials and the URL of the download server service using YaST.

Setting the Update Server Credentials with YaST
Figure 2.1: Setting the Update Server Credentials with YaST
  1. Switch to the Customer Center Access section in the SMT Configuration. If the credentials have been already set with YaST or via the /etc/smt.conf configuration file, they will be displayed in the User and Password fields.

  2. If you do not have credentials, visit SUSE Customer Center to obtain them. For more details, see Section 3.1, “Mirroring Credentials”.

  3. Enter your user name and password in the appropriate fields.

  4. Click Test to check the credentials. YaST will try to download a list of available repositories with the provided credentials. If the test succeeds, the last line of the test results will read Test result: success. If the test fails, check the provided credentials and try again.

    Successful Test of the Update Server Credentials
    Figure 2.2: Successful Test of the Update Server Credentials
  5. Enter the SCC E-mail Used for Registration. This should be the address you used to register to SUSE Customer Center.

    Enter Your SMT Server URL if it has not been detected automatically.

  6. Click OK.

2.3 Setting SMT Database Password with YaST

For security reasons, SMT uses its own user in the database. YaST provides an interface for setting up or changing the SMT database password. To set or change the SMT database password with YaST, follow the steps below.

  1. Switch to the Database and Reporting section in the SMT Configuration module.

  2. Enter the Database Password for SMT User. Confirm the password by re-entering it, then click OK.

2.4 Setting E-mail Addresses to Receive Reports with YaST

YaST SMT provides an interface for setting up a list of e-mail addresses for receiving reports from SMT. To edit this list of addresses, proceed as follows.

  1. Switch to the Database and Reporting section in the SMT Configuration.

  2. The list of e-mail addresses is shown in the table. Use the appropriate buttons to add, edit, and delete existing address entries.

  3. Click OK.

The comma-separated list of addresses for SMT reports is written to the reportEmail section of the /etc/smt.conf configuration file.

2.5 Setting the SMT Job Schedule with YaST

The SMT Configuration module provides an interface to schedule recurring SMT jobs. YaST uses cron to schedule configured jobs. If needed, cron can be used directly. There are five types of recurring jobs that can be set:

Synchronization of Updates

Synchronizes with SUSE Customer Center, updates repositories, and downloads new updates.

Generation of Reports

Generates and sends SMT Subscription Reports to addresses defined in Section 2.4, “Setting E-mail Addresses to Receive Reports with YaST”.

SCC Registration

Registers with SUSE Customer Center all clients that are not already registered or that changed their data since the last registration.

Job Queue Cleanup

Cleans up queued jobs. It removes finished or failed jobs from the job queue that are older than eight days. It also removes job artifacts that are left in the database as result of an error.

SMT Job Schedule Configuration
Figure 2.3: SMT Job Schedule Configuration

Use the following procedure to configure the schedule of SMT jobs with YaST.

  1. Switch to the Scheduled SMT Jobs section in the SMT Configuration. The table contains a list of all scheduled jobs, their type, frequency, date, and time to run. You can add, delete, and edit the existing scheduled tasks.

  2. To add a scheduled SMT job, click Add. This opens the Adding New SMT Scheduled Job dialog.

    Choose the synchronization job to schedule. You can choose between Synchronization of Updates, Report Generation, SCC Registration, and Job Queue Cleanup.

    Choose the Frequency of the new scheduled SMT job. Jobs can be performed Daily, Weekly, Monthly, or Periodically (every n-th hour or every m-th minute).

    Set the Job Start Time by entering Hour and Minute. In case of a recurring job, enter the relevant intervals. For weekly and monthly schedules, select Day of the Week or Day of the Month.

    Click Add.

  3. To edit a scheduled SMT job (for example, change its frequency, time, or date), select the job in the table and click Edit. Then change the desired parameters and click OK.

    Setting Scheduled Job with YaST
    Figure 2.4: Setting Scheduled Job with YaST
  4. To cancel a scheduled job and delete it from the table, select the job in the table and click Delete.

  5. Click OK to apply the settings and quit the SMT Configuration.

3 Mirroring Repositories on the SMT Server

  • Filename: smt_mirroring.xml
  • ID: smt.mirroring

You can mirror the installation and update repositories on the SMT server. This way, you do not need to download updates on each machine, which saves time and bandwidth.

Important
Important: SUSE Linux Enterprise Server 9 Repositories

As SUSE Linux Enterprise Server 9 is no longer supported, SMT does not mirror SUSE Linux Enterprise Server 9 repositories.

3.1 Mirroring Credentials

Before you create a local mirror of the repositories, you need appropriate organization credentials. You can obtain the credentials from SUSE Customer Center.

To get the credentials from SUSE Customer Center, follow these steps:

  1. Visit SUSE Customer Center at http://scc.suse.com and log in.

  2. If you are member of multiple organizations, chose the organization you want to work with from the drop-down box in the top-right corner.

  3. Click Organization in the top menu.

  4. Switch to the Organizational credentials section.

  5. To see the password, click Show password.

The obtained credentials should be set with the YaST SMT Server Configuration module or added directly to the /etc/smt.conf file. For more information about the /etc/smt.conf file, see Section 7.2.1, “/etc/smt.conf”.

Tip
Tip: Merging Multiple Organization Site Credentials

SMT can only work with one mirror credential at a time. Multiple credentials are not supported. When a customer creates a new company, this generates a new mirror credential. This is not always convenient, as some products are available via the first set and other products via the second set. To request a merge of credentials, the EMEA-based customers (Europe, the Middle East and Africa) are advised to send an e-mail to <> with the applicable customer and site IDs. The EMEA PIC team will verify the records. The contact for NALAAP (North America, Latin America, and Asia Pacific) is <>.

3.2 Managing Software Repositories with SMT Command Line Tools

This section describes tools and procedures for viewing information about software repositories available through SMT, configuring these repositories, and setting up custom repositories on the command line. For details on the YaST SMT Server Management module, see Chapter 4, Managing Repositories with YaST SMT Server Management.

3.2.1 Updating the Local SMT Database

The local SMT database needs to be updated periodically with the information downloaded from SUSE Customer Center. These periodic updates can be configured with the SMT Management module, as described in Section 2.5, “Setting the SMT Job Schedule with YaST”.

To update the SMT database manually, use the smt-sync command. For more information about the smt-sync command, see Section 7.1.2.7, “smt-sync”.

3.2.2 Enabled Repositories and Repositories That Can Be Mirrored

The database installed with SMT contains information about all software repositories available on SUSE Customer Center. However, the used mirror credentials determine which repositories can really be mirrored. For more information about getting and setting organization credentials, see Section 3.1, “Mirroring Credentials”.

Repositories that can be mirrored have the MIRRORABLE flag set in the repositories table in the SMT database. That a repository can be mirrored does not mean that it needs to be mirrored. Only repositories with the DOMIRROR flag set in the SMT database will be mirrored. For more information about configuring which repositories should be mirrored, see Section 3.2.4, “Selecting Repositories to Be Mirrored”.

3.2.3 Getting Information about Repositories

Use the smt-repos command to list available software repositories and additional information. Using this command without any options lists all available repositories, including repositories that cannot be mirrored. In the first column, the enabled repositories (repositories set to be mirrored) are marked with Yes. Disabled repositories are marked with No. The other columns show ID, type, name, target, and description of the listed repositories. The last columns show whether the repository can be mirrored and whether staging is enabled.

Use the --verbose option, to get additional information about the URL of the repository and the path it will be mirrored to.

The repository listing can be limited to the repositories that can be mirrored or to the repositories that are enabled. To list the repositories that can be mirrored, use the -m or --only-mirrorable option: smt-repos -m.

To list only enabled repositories, use the -o or --only-enabled option: smt-repos -o (see Example 3.1, “Listing All Enabled Repositories”).

Example 3.1: Listing All Enabled Repositories
tux:~ # smt-repos -o
.---------------------------------------------------------------------------------------------------------------------.
| Mirr| ID | Type | Name                    | Target        | Description                             | Can be M| Stag|
+-----+----+------+-------------------------+---------------+-----------------------------------------+---------+-----+
| Yes |  1 | zypp | ATI-Driver-SLE11-SP2    | --            | ATI-Driver-SLE11-SP2                    | Yes     | Yes |
| Yes |  2 | zypp | nVidia-Driver-SLE11-SP2 | --            | nVidia-Driver-SLE11-SP2                 | Yes     | No  |
| Yes |  3 | nu   | SLED11-SP2-Updates      | sle-11-x86_64 | SLED11-SP2-Updates for sle-11-x86_64    | Yes     | No  |
| Yes |  4 | nu   | SLES11-SP1-Updates      | sle-11-x86_64 | SLES11-SP1-Updates for sle-11-x86_64    | Yes     | Yes |
| Yes |  5 | nu   | SLES11-SP2-Core         | sle-11-x86_64 | SLES11-SP2-Core for sle-11-x86_64       | Yes     | No  |
| Yes |  6 | nu   | SLES11-SP2-Updates      | sle-11-i586   | SLES11-SP2-Updates for sle-11-i586      | Yes     | No  |
| Yes |  7 | nu   | WebYaST-Testing-Updates | sle-11-i586   | WebYaST-Testing-Updates for sle-11-i586 | Yes     | No  |
'-----+----+------+-------------------------+---------------+-----------------------------------------+---------+-----'

You can also list only repositories with a specific name or show information about a repository with a specific name and target. To list repositories with a particular name, use the smt-repos REPOSITORY_NAME command. To show information about a repository with a specific name and target, use the smt-repos repository_name TARGET command.

To get a list of installation repositories from remote, see Section 8.7, “Listing Accessible Repositories”.

3.2.4 Selecting Repositories to Be Mirrored

Only enabled repositories can be mirrored. In the database, the enabled repositories have the DOMIRROR flag set. Repositories can be enabled or disabled using the smt-repos command.

To enable one or more repositories, follow these steps:

  1. To enable all repositories that can be mirrored or to choose one repository from the list of all repositories, run the smt-repos -e command.

    You can limit the list of repositories by using the relevant options. To limit the list to the repositories that can be mirrored, use the -m option: smt-repos -m -e. To limit the list to the repositories with a specific name, use the smt-repos -e REPOSITORY_NAME command. To list a repository with a specific name and target, use the smt-repos -e REPOSITORY_NAME TARGET command.

    To enable all repositories belonging to a specific product, use the --enable-by-prod or -p option, followed by the name of the product and optionally version, architecture, and release:

    smt-repos -p product[,version[,architecture[,release]]]

    For example, to enable all repositories belonging to SUSE Linux Enterprise Server 10 SP3 for PowerPC architecture, use the smt-repos -p SUSE-Linux-Enterprise-Server-SP3,10,ppc command. The list of known products can be obtained with the smt-list-products command.

    Tip
    Tip: Installer Self-Update Repository

    SMT supports mirroring the installer self-update repository (find more information in Section 6.4.1, “Self-Update Process”). If you need to provide the self-update repository, identify and enable it, for example:

    $ smt-repos -m | grep Installer
    $ smt-repos -e SLES12-SP2-Installer-Updates sle-12-x86_64
  2. If more than one repository is listed, choose the one you want to enable: specify its ID listed in the repository table and press Enter. If you want to enable all the listed repositories, use a and press Enter.

To disable one or more repositories, follow these steps:

  1. To disable all enabled repositories or just choose one repository from the list of all repositories, run the smt-repos -d command.

    To choose the repository to be disabled from a shorter list, or to disable all repositories from a limited group, use any of the available options to limit the list of repositories. To limit the list to the enabled repositories, use the -o option: smt-repos -o -d. To limit the list to repositories with a particular name, use the smt-repos -d REPOSITORY_NAME command. To show a repository with a specific name and target, use the smt-repos -d REPOSITORY_NAME TARGET command.

  2. If more than one repository is listed, choose which one you want to disable: specify its ID listed in the repository table and press Enter. If you want to disable all the listed repositories, use a and press Enter.

3.2.5 Deleting Mirrored Repositories

You can delete mirrored repositories that are no longer used. If you delete a repository, it will be physically removed from the SMT storage area.

Use the smt-repos --delete command to delete a repository with a specific name. To delete the repository in a namespace, specify the --namespace DIRNAME option.

The --delete option lists all repositories. You can delete the specified repositories by entering the ID number or the name and target. To delete all repositories, enter a.

Note
Note: Detecting Repository IDs

Every repository has an SHA-1 hash that you can use as an ID. You can get the repository's hash by calling smt-repos -v.

3.2.6 Mirroring Custom Repositories

SMT also makes it possible to mirror repositories that are not available at the SUSE Customer Center. These repositories are called custom repositories, and they can be mirrored using the smt-setup-custom-repos command. It is also possible to delete custom repositories.

When adding a new custom repository, the smt-setup-custom-repos command inserts a new record in the database and sets the mirror flag to true. You can disable mirroring later, if necessary.

To set up a custom repository to be available through SMT, follow these steps:

  1. If you do not know the ID of the product the new repositories should belong to, use smt-list-products to get the ID. For the description of the smt-list-products, see Section 7.1.2.4, “smt-list-products”.

  2. Run

    smt-setup-custom-repos --productid PRODUCT_ID \
    --name REPOSITORY_NAME --exturl REPOSITORY_URL

    PRODUCT_ID is the ID of the product the repository belongs to, REPOSITORY_NAME is the name of the repository, and REPOSITORY_URL is the URL of the repository. If the added repository needs to be available for more than one product, specify the IDs of all products that should use the added repository.

    For example, the following command sets My repository available at http://example.com/My_repository to the products with the IDs 423, 424, and 425:

    smt-setup-custom-repositories --productid 423 --productid 424 \
    --productid 425 --name 'My_repository' \
    --exturl 'http://example.com/My_repository'
Note
Note: Mirroring Unsigned Repositories

By default, SUSE Linux Enterprise 10 does not allow the use of unsigned repositories. So if you want to mirror unsigned repositories and use them on client machines, be aware that the package installation tool—YaST or zypper—will ask you whether to use repositories that are not signed.

To remove an existing custom repository from the SMT database, use smt-setup-custom-repositories --delete ID, where ID is the ID of the repository to be removed.

3.3 The Structure of /srv/www/htdocs for SLE 11

The path to the directory containing the mirror is set by the MirrorTo option in the /etc/smt.conf configuration file. For more information about /etc/smt.conf, see Section 7.2.1, “/etc/smt.conf”. If the MirrorTo option is not set to the Apache htdocs directory /srv/www/htdocs/, the following links need to be created. If the directories already exist, they need to be removed prior to creating the link (the data in these directories will be lost). In the following examples, MIRRORTO needs to be replaced by the path the option MirrorTo is set to.

  • /srv/www/htdocs/repo/$RCE must point to MIRRORTO/repo/$RCE/

  • /srv/www/htdocs/repo/RPMMD must point to MIRRORTO/repo/RPMMD/

  • /srv/www/htdocs/repo/testing must point to MIRRORTO/repo/testing/

  • /srv/www/htdocs/repo/full must point to MIRRORTO/repo/full/

The directory specified using the MirrorTo option and the subdirectories listed above must exist. Files, directories, and links in /MIRRORTO must belong to the smt user and the www group.

Here is an example where the MirrorTo is set to /mirror/data:

l /srv/www/htdocs/repo/
total 16
lrwxrwxrwx 1 smt  www    22 Feb  9 14:23 $RCE -> /mirror/data/repo/$RCE/
drwxr-xr-x 4 smt  www  4096 Feb  9 14:23 ./
drwxr-xr-x 4 root root 4096 Feb  8 15:44 ../
lrwxrwxrwx 1 smt  www    23 Feb  9 14:23 RPMMD -> /mirror/data/repo/RPMMD/
lrwxrwxrwx 1 smt  www    22 Feb  9 14:23 full -> /mirror/data/repo/full/
drwxr-xr-x 2 smt  www  4096 Feb  8 11:12 keys/
lrwxrwxrwx 1 smt  www    25 Feb  9 14:23 testing -> /mirror/data/repo/testing/
drwxr-xr-x 2 smt  www  4096 Feb  8 14:14 tools/

The links can be created using the ln -s commands. For example:

cd /srv/www/htdocs/repo
for LINK in \$RCE RPMMD full testing; do
 ln -s /mirror/data/repo/${LINK}/ && chown -h smt.www ${LINK}
done
Important
Important: The /srv/www/htdocs/repo Directory

The /srv/www/htdocs/repo directory must not be a symbolic link.

Important
Important: Apache and Symbolic Links

By default Apache on SUSE Linux Enterprise Server is configured to not follow symbolic links. To enable symblic links for /srv/www/htdocs/repo/ add the following snippet to /etc/apache2/default-server.conf (or the respetive virtual host configurtion in case you are running SMT on a virtual host):

<Directory "/srv/www/htdocs/repo">
 Options FollowSymLinks
</Directory>

After having made the change, test the syntax and reload the Apache configuration files to activate the change:

rcapache2 configtest && rcapache2 reload

3.4 The Structure of /srv/www/htdocs for SLE 12

The repository structure in the /srv/www/htdocs directory matches the structure specified in SUSE Customer Center. There are the following directories in the structure (selected examples, similar for other products and architectures):

repo/SUSE/Products/SLE-SDK/12/x86_64/product/

Contains the -POOL repository of SDK (the GA version of all packages).

repo/SUSE/Products/SLE-SDK/12/x86_64/product.license/

Contains EULA associated with the product.

repo/SUSE/Updates/SLE-SDK/12/x86_64/update/
repo/SUSE/Updates/SLE-SDK/12/s390x/update/
repo/SUSE/Updates/SLE-SERVER/12/x86_64/update/

Contain update repositories for respective products.

repo/full/SUSE/Updates/SLE-SERVER/12/x86_64/update/
repo/testing/SUSE/Updates/SLE-SERVER/12/x86_64/update/

Contain repositories created for staging of respective repositories.

3.5 Using the Test Environment

You can mirror repositories to a test environment instead of the production environment. The test environment can be used with a limited number of client machines before the tested repositories are moved to the production environment. The test environment can be run on the main SMT server.

The testing environment uses the same structure as the production environment, but it is located in the /srv/www/htdocs/repos/testing/ subdirectory.

To mirror a repository to the testing environment, you can use the Staging tab in the YaST SMT Management module, or the command smt-staging.

To register a client in the testing environment, modify /etc/SUSEConnect on the client machine as follows:

namespace: testing

To move the testing environment to the production environment, manually copy or move it using the cp -a or mv command.

You can enable staging for a repository in the Repositories tab of the SMT Management module or with the smt-repos command. The mirroring happens automatically to repo/full/.

If you have an SLE11-based update repository with patches, SMT tools can be used to manage them. Using these tools, you can select patches and create a snapshot and copy it into repo/testing/. After tests are finished, you can copy the contents of repo/testing into the production area /repo.

SLE10-based update repositories are not supported by SMT tools. Not all of these repositories support selective staging. In this case, you must mirror the complete package.

Recommended workflow:

customer center => repo/full => repo/testing, => repo/production

3.6 Testing and Filtering Update Repositories with Staging

You can test repositories on any clients using the smt-staging command before moving them to the production environment. You can select new update repositories to be installed on clients.

You can either use the smt-staging command or the YaST SMT Management module for staging. For more details, see Section 4.3, “Staging Repositories”.

SMT Staging Schema
Figure 3.1: SMT Staging Schema

Repositories with staging enabled are mirrored to the /MIRRORTO/repo/full subdirectory. This subdirectory is usually not used by your clients. Incoming new updates are not automatically visible to the clients before you get a chance to test them. Later, you can generate a testing environment of this repository, which goes to the /MIRRORTO/repo directory.

If you have an SLE 11-based update repository with patches, you can use SMT tools to manage them. Using these tools, you can select patches and create a snapshot and put it into repo/testing/. After tests are finished, you can put the content of repo/testing into the /repo production area called the default staging group. You can create additional staging groups as needed using the smt-staging creategroup command.

Note
Note: SLE 10-based Update Repositories

SLE 10-based update repositories are not supported by SMT tools. Not all of these repositories support selective staging. In this case, you need to mirror the complete package.

Enabling Staging

To enable or disable staging, use the smt-repos command with the --enable-staging or -s options:

smt-repos --enable-staging

You can enable the required repositories by entering the ID number or by entering the name and target. If you want to enable all repositories, enter a.

Generating Testing and Production Snapshots

To create the testing repository in the default staging group, run the following command:

smt-staging createrepo REPOSITORY_ID -–testing

You can then test the installation and functionality of the patches in testing clients. If testing was successful, create the production repository:

smt-staging createrepo REPOSITORY_ID --production

To create testing and production repositories in a named staging group, create the group and the repositories in this group:

smt-staging creategroup GROUPNAME TESTINGDIR PRODUCTIONDIR
smt-staging createrepo --group GROUPNAME REPOSITORY_ID -–testing
SMT-STAGING createrepo --group GROUPNAME REPOSITORY_ID -–production

This can be useful when you want to combine SLES11-SP1-Updates and SLES11-SP2-Updates of the sle-11-x86_64 architecture into one repository of a group:

smt-staging creategroup SLES11SP1-SP2-Up test-sp1-sp2 prod-sp1-sp2
smt-staging createrepo --group SLES11SP1-SP2-Up \
  SLES11-SP1-Updates sle-11-x86_64 --testing
smt-staging createrepo --group SLES11SP1-SP2-Up \
  SLES11-SP2-Updates sle-11-x86_64 --testing
smt-staging createrepo --group SLES11SP1-SP2-Up \
  SLES11-SP1-Updates sle-11-x86_64 --production
smt-staging createrepo --group SLES11SP1-SP2-Up \
  SLES11-SP2-Updates sle-11-x86_64 --production

Group names can contain the following characters: -_, a-z A-Z, and 0-9.

Filtering Patches

You can allow or forbid all or selected patches using the allow or forbid commands:

smt-staging forbid --patch ID
smt-staging forbid --category CATEGORYNAME
Signing Changed Repositories

Filtering one or more patches from a repository invalidates the original signature, and the repository needs to be signed again. The smt-staging createrepo command does that automatically, provided you configure the SMT server.

To enable signing of changed metadata, the admin needs to generate a new signing key. This can be done with GPG like this:

mkdir DIR
gpg --gen-key --homedir DIR
sudo mv DIR /var/lib/smt/.gnupg
sudo chown smt:users -R /var/lib/smt/.gnupg
sudo chmod go-rwx -R /var/lib/smt/.gnupg

The ID of the newly generated key can be obtained using the gpg --gen-key command. The ID must be added to the signingKeyID option in the /etc/smt.conf file.

At this point, the clients are not aware of the new key. Import the new key to clients during their registration as follows:

sudo -u smt gpg --homedir /var/lib/smt/.gnupg \
  --export -a SIGNING_KEYID \
  > /MIRRORTO/repo/keys/smt-signing-key.key

In this example, MIRRORTO is the base directory where repositories will be mirrored. After that, clients can import this key during the registration process.

Registering Clients in the Testing Environment

To register a client in the testing environment, modify the /etc/SUSEConnect file on the client machine:

namespace: testing

3.7 Repository Preloading

Deploying multiple SMT servers can take time if each new SMT server must mirror the same repositories.

To save time when deploying new SMT servers, the repositories can be preloaded from another server or disk instead. To do this, follow these steps:

  1. Enable the repositories to be mirrored with the SMT, for example:

    smt-repos -e SLES12-Updates sle-12_x86_64
  2. Perform a dry run of smt-mirror to create the required repository directories:

    smt-mirror -d --dryrun -L /var/log/smt/smt-mirror.log

    The following directories are created based on the repository above and the default MirrorTo:

    /srv/www/htdocs/repo/repoindex.xml
    /srv/www/htdocs/repo/$RCE/SLES12-Updates/sle-12-x86_64/*
  3. Then copy the repositories from another SMT server, for example:

    rsync -av 'smt12:/srv/www/htdocs/repo/\$RCE/SLES12-Updates/sle-12-x86_64/' \
     '/srv/www/htdocs/repo/$RCE/SLES12-Updates/sle-12-x86_64/'
  4. To get the repository data fixed, run the following command:

    smt-mirror -d -L /var/log/smt/smt-mirror.log
Important
Important: Possible Error Messages

Errors, such as repomd.xml is the same, but repo is not valid. Start mirroring., are considered normal. They occur because the metadata of the preloaded repositories in the server's database remains incorrect until the initial mirror of the repositories has completed.

4 Managing Repositories with YaST SMT Server Management

  • Filename: smt_management.xml
  • ID: smt.management

The YaST SMT Server Management module is designed to perform daily management tasks. It can be used to enable and disable the mirroring of repositories, the staging flag for repositories, and perform the mirroring and staging.

4.1 Starting SMT Management Module

SMT Management is a YaST module. There are two ways to start the module:

  • Start YaST and select Network Services, then SMT Server Management

  • Run the yast2 smt command in the terminal as root

This opens the SMT Management application window and switches to the Repositories section.

List of Repositories
Figure 4.1: List of Repositories

4.2 Viewing and Managing Repositories

In the Repositories section, you can see the list of all available package repositories for SMT. For each repository, the list shows the repository's name, target product and architecture, mirroring and staging flag, date of last mirroring, and a short description. Sort the list by clicking the desired column header, and scroll the list items using the scrollbar on the right side.

4.2.1 Filtering Repositories

You can also filter out groups of repositories using the Repository Filter text box. Enter the desired filter term and click Filter to see only the matching entries. To cancel the current filter and display all repositories, clear the Repository Filter field and click Filter.

Repository Filter
Figure 4.2: Repository Filter

4.2.2 Mirroring Repositories

Before you can offer package repositories, you need to create a local mirror of their packages. To do this, follow the procedure below.

  1. From the list, select the line containing the name of the repository you want to mirror.

  2. Click the selected line to highlight it.

  3. Click the Toggle Mirroring button in the lower-left part of the window. This enables the option in the Mirroring column of the selected repository. If the repository was already selected for mirroring, clicking the Toggle Mirroring button disables the mirroring.

  4. Hit the Mirror Now button to mirror the repository.

  5. A pop-up window appears with the information about mirroring status and result.

  6. Click OK to refresh the list of repositories.

Status of Mirroring Process
Figure 4.3: Status of Mirroring Process

4.3 Staging Repositories

After the mirroring is finished, you can stage the mirrored repositories. In SMT, staging is a process where you create either testing or production repositories based on the mirrored ones. The testing repository helps you examine the repository and its packages before you make them available in a production environment. To make repositories available for staging, follow the steps below.

  1. From the repository list, select the line containing the name of the repository you want to manage.

  2. Click the selected line to highlight it.

  3. Click the Toggle Staging button next to the Toggle Mirroring button. This enables the option in the Staging column of the selected repository. If the repository was already selected for staging before, clicking the Toggle Staging button disables staging.

  4. Repeat steps 1 to 3 for all directories you want to stage.

Important
Important: Toggle Staging Button Not Active

You can only stage the repositories that were previously selected for mirroring. Otherwise, the Toggle Staging button will disabled.

After you have mirrored the repositories and made them available for staging, click the Staging tab. In the upper-left part of the window, you will find the Repository Name drop-down box containing all repositories available for staging. The repository names there have the name of the attached staging group. Select the group you want to stage, and you should see a list of packages in this repository. For each patch, there is information about the patch name, its version and category, testing and production flags, and a short summary.

Next to the Repository Name drop-down box, there is a Patch Category filter. It can be used for listing only the patches that belong to one of the predefined categories.

If the selected repository allows for patch filtering, you can toggle the status flag for individual patches. This is done by clicking the Toggle Patch Status button.

Before creating a repository of packages that are available in the production environment, you need to create and test the testing repository. Select the From Full Mirror to Testing item from the Create Snapshot drop-down list. A small pop-up window appears informing you about the staging process. After the testing repository snapshot has been created, you should see the appropriate options enabled in the Testing column.

Testing Created Snapshot
Figure 4.4: Testing Created Snapshot
Important
Important: Creating a Production Snapshot

After you have enabled staging for an update repository, you need to create its production snapshot to make it available to the clients. Otherwise, the clients cannot find the update repository.

Select the From Testing to Production item from the Create Snapshot drop-down box. A small pop-up window appears informing you about linking the testing repository to the production one. After the production snapshot has been created, you should see the appropriate options enabled in the Production column. Also, a green check mark appears in the Repository Name drop-down box.

4.4 Jobs and Client Status Monitoring

For each client that is registered against the SMT server, SMT creates a job queue. To use the job queue, you need to install the smt-client package on the client. During the installation of the smt-client package, a cron job is created that runs the client executable /usr/sbin/smt-agent every three hours. The agent then asks the server if it has any jobs in the queue belonging to this client and executes these jobs. When there are no more jobs in the queue, the agent terminates completely. It is important to understand that jobs are not pushed directly to the clients when they get created. They are not executed until the client asks for them at the intervals specified in the cron job. Therefore, from the time a job is created on the server until it is executed on the client, a delay of several hours may occur.

Every job can have a parent job. This means that the child job only runs after the parent job has successfully finished. It is also possible to configure advanced timing and recurrence and persistence of jobs. You can find more details about SMT jobs in Section 7.1.2.3, “smt-job”.

When creating jobs, you need to specify the GUID of the target clients using the -g GUID parameter. Although the -g parameter can be specified multiple times in a single command, you cannot use wild cards to assign a job to all clients.

Currently, the following types of jobs are available:

Execute

Run commands on the client

Eject

Open, close, or toggle the CD tray of the client

Patchstatus

Report the status of installed patches

Reboot

Reboot the client

Softwarepush

Install packages

Update

Install available updates

Tip
Tip: Default Job Types

By default only softwarepush, patchstatus, and update jobs are allowed. To allow more types of jobs, append the job type to the ALLOWED_AGENTS list in /etc/sysconfig/smt-client.

All clients that register against the SMT server automatically get a persistent patchstatus job added to their job queue. This is also the case for clients without the smt-clients package (SUSE Linux Enterprise 10 and older, or non-SUSE based distributions). These clients appear with the Unknown patchstatus in the client lists. The patchstatus jobs for such clients are not required, and clients can safely be deleted to clean up the output of smt-job. Keep in mind that if you update a machine to SUSE Linux Enterprise 11 or later, you need to create the patchstatus job manually.

Whenever the client runs a patchstatus job, it compares the currently installed updates with what is available in the repositories on the SMT server. The job then reports back the number of missing patches that need to be installed in each of the four categories:

  • Security

  • Package Manager

  • Recommended

  • Optional

Tip
Tip: The --agreelicense Option

To install a package and its dependencies, the job type softwarepush is used. When creating this type of job, it is a good idea to use the --agreelicense option. If a package displays a license agreement and expects it to be accepted, the job will skip the package if --agreelicense is not specified. The smt-client command forwards the installation process to zypper, which does not consider a failed acceptance of a license agreement to be an error. This results in the job being completed successfully, even if the package is not installed. Using the --agreelicense option prevents this from happening.

4.4.1 Checking the Client Status with YaST

The Clients Status section of the SMT Management window provides the status information about all the clients that use the repositories on your SMT server. This information consists of two main parts: the list of the clients and the detailed information.

You can see the client's host name, the date and time of the last network contact with the SMT server, and its update status. The update status can be one of the following:

Up-to-date

The client packages are updated to their last version available in the production repository

Updates available

This status means that there are updates available for the client that are either optional or recommended

Critical

Either security patches or package manager patches are available for the client

Detailed information about the selected client is available in the lower part of the window. This usually includes extended status information and detailed information about the number and types of available updates.

Clients Status
Figure 4.5: Clients Status

The date and time in the Last Contact column is the last time contact of the server—even if it only ran the regular registration update script. This date is not the date of the last 'patchstatus' report. The smt-client command-line tool prints the correct date and calls it Patch Status Date. The smt-client -v command prints both dates: the patchstatus date and the last contact of the client system.

Note
Note: Hidden Patches

Some patches may not be visible if they are required by other patches that are only shown as available after the package manager patch or patches have been installed.

5 Managing Client Machines with SMT

  • Filename: smt_registration.xml
  • ID: smt.registration

SMT lets you register and manage client machines on SUSE Customer Center. Client machines must be configured to use SMT. For information about configuring clients to use SMT, see Chapter 8, Configuring Clients to Use SMT.

5.1 Listing Registered Clients

To list SMT-registered client machines, use the smt-list-registrations command. The following information is listed for each client: its Unique ID, Hostname, date and time of Last Contact with the SMT server, and the Software Product the client uses.

5.2 Deleting Registrations

To delete a registration from SMT and SUSE Customer Center, use the following command:

smt-delete-registration -g
Client_ID

To delete multiple registrations, the option -g can be used several times.

The ID of the client machine to be deleted can be determined from the output of the smt-list-registrations command.

5.3 Manual Registration of Clients at SUSE Customer Center

The smt-register command registers clients at SUSE Customer Center. This registers all unregistered clients and clients with data that changed since the last registration.

To register clients whose registration has failed, use the --reseterror option. This option resets the SCC registration error flag and tries to submit registrations again.

5.4 Scheduling Periodic Registrations of Clients at SUSE Customer Center

SMT module allows for the easy scheduling of client registrations. By default, registrations are scheduled to run every 15 minutes. To create or modify a new registration schedule, follow the steps below.

  1. Start YaST SMT Configuration module (yast2 smt-server).

  2. Go to the Scheduled SMT Job.

  3. Select any SCC Registration job and click Edit to change its schedule.

    To create a new registration schedule, click Add and select SCC Registration as Job to Run.

  4. Choose the Frequency of the scheduled SMT job. You can perform jobs Daily, Weekly, Monthly, or Periodically (every n-th hour or every m-th minute).

    Set the Job Start Time by entering the Hour and Minute or appropriate time periods. For weekly and monthly schedules, select the Day of the Week or the Day of the Month the mirroring should occur.

    Note
    Note: Lowest Registration Frequency

    Do not set the frequency lower than 10 minutes, because the maximum value of the rndRegister is 450 (7.5 minutes). If the frequency is lower, it may happen that the started process is still sleeping when the next process starts. This causes the second request to exit.

  5. Click OK or Add and Finish.

Scheduling of SMT jobs in general is covered in Section 2.5, “Setting the SMT Job Schedule with YaST”.

YaST uses cron to schedule SUSE Customer Center registrations and other SMT jobs. If you prefer not to use YaST, you can use cron directly.

To disable automatic registration, change the forwardRegistration value in the [LOCAL] section of the /etc/smt.conf configuration file to false.

5.5 Compliance Monitoring

To assist customers in monitoring their license compliance, SMT generates a weekly report based on data from SMT and SUSE Customer Center. This report contains information about statistics of the registered machines, products used, and of the active, expiring or missing license subscriptions. If subscriptions are about to expire and/or more SUSE Linux Enterprise machines are registered than you have purchased licenses for, the report contains relevant warnings.

To calculate the compliance, the smt-report tool by default downloads information about the subscriptions and registrations (this can be disabled).

You can configure the recipient addresses for the reports in the Database and Reporting section of the YaST Subscription Management Tool configuration module. All of the e-mail configuration options are located in the [REPORT] section of /etc/smt.conf and explained in Section 7.2.1.6, “[REPORT] Section of /etc/smt.conf”.

The scheduling of the reports is configured in /etc/cron.d/novell.com-smt, while the parameters to use with the cron jobs are in the REPORT_PARAMS section of /etc/smt.d/smt-cron.conf.

Describing the content of the reports is beyond the scope of this section, but a set of reports can be split into five individual parts. By default, these reports are attached as individual files to the mail on the weekly report run. The alerts report is a normal text file while the others are in CSV format. The reports can also be created in PDF or XML by specifying --pdf or --xml as output format.

To generate a set of reports as CSV files based on local data and to display them in the standard output, run the following command:

smt-report --local --csv --file /root/smt-local-rep
Tip
Tip: Directory for Reports

The example stores the reports in the /root directory. You can change it to any other writable directory.

The command generates the following files:

/root/smt-local-rep-product_subscription_active.csv
/root/smt-local-rep-product_subscription_alerts.txt
/root/smt-local-rep-product_subscription_expired.csv
/root/smt-local-rep-product_subscription_expiresoon.csv
/root/smt-local-rep-product_subscription_summary.csv
Note
Note: Multiple SMT Servers

If you have multiple SMT servers, the reports may not include all SMT servers or machines in your environment. For the complete statistics of all your registered machines, refer to the information provided by SUSE Customer Center.

For more information about types of reports, output formats, and targets refer to Chapter 6, SMT Reports.

6 SMT Reports

  • Filename: smt_reporting.xml
  • ID: smt.reporting

This chapter explains how to generate reports using the data from the SMT and SUSE Customer Center. These reports contain statistics of all the registered machines, products used and all active, expiring or missing subscriptions.

Note
Note: Assignment of Reports

If you are using more than one SMT server, generated reports may not include all SMT servers or machines in your environment. For the complete statistics of all your registered machines, refer to the information in the SUSE Customer Center.

6.1 Report Schedule and Recipients

Generated SMT reports can be periodically sent to a list of specified e-mail addresses. To create or edit this list and to set the frequency of the reports, use the YaST SMT Configuration module. How to configure this list is described in Section 2.4, “Setting E-mail Addresses to Receive Reports with YaST”. Configuration of the report schedule is covered in Section 2.5, “Setting the SMT Job Schedule with YaST”.

The list can also be edited manually in the reportEmail part of the /etc/smt.conf configuration file. For more information about manually editing the list of addresses, see Section 7.2.1.6, “[REPORT] Section of /etc/smt.conf”. To set the frequency of reports manually, you can edit the smt-gen-report lines of the crontab in /etc/cron.d/novell.com-smt. For more information about the crontab format, see man 5 crontab.

Reports, including those generated as a scheduled SMT job, are created by the smt-report command. This command supports various parameters. To edit parameters used with scheduled commands, edit the /etc/smt.d/smt-cron.conf configuration file. For more information, see Section 7.2.2, “/etc/smt.d/smt-cron.conf”.

6.2 Report Output Formats and Targets

SMT reports can be printed to the standard output, exported to one or multiple files (in the CSV format), and mailed to a specified list of e-mail addresses. The following parameters can be used with the smt-report command:

--quiet or -q

Suppress output to STDOUT and run smt-report in quiet mode.

--file or -F

Export the report to one or several files. By default, the report is written to a single file, with the results formatted as tables. Optionally, the file name or whole path may be specified after the parameter: --file FILENAME. If no file name is specified, the default file name containing a time stamp is used. However, SMT will not check if the file or files already exist.

In the CSV (Comma-Separated Value) mode, the report is written to multiple files, therefore the specified file name expands to [PATH/]FILENAME-reportname.extension for every report.

--csv or -c

The report is exported to multiple files in the CSV format. The first line of each *.csv file consists of the column names. It is recommended to use the --csv parameter together with the --file parameter. If the specified file name contains a .csv extension, the report format will be CSV (as if the --csv parameter was used).

--mail or -m

Send the report to the addresses configured using the YaST SMT Configuration module and stored in /etc/smt.conf. The report is rendered as tables.

--attach or -a

Attach the report to the mails in the CSV format. This option should only be used in combination with the --mail option.

--pdf

The report is exported to multiple files in the PDF format.

--xml

The report is exported to multiple files in the XML format.

Note
Note: Disabling Sending Attachments

To disable sending CSV attachments with report mails, edit the /etc/smt.d/smt-cron.conf configuration file as follows: remove the --attach option from the REPORT_PARAMS value. The default line reads: REPORT_PARAMS="--mail --attach -L /var/log/smt-report.log". To disable CSV attachments, change it to: REPORT_PARAMS="--mail -L /var/log/smt-report.log".

If you have disabled CSV attachments but need them occasionally, you can send them manually with the smt-report --mail --attach -L /var/log/smt-report.log command.

7 SMT Tools and Configuration Files

  • Filename: smt_tools.xml
  • ID: smt.tools

This chapter describes the most important scripts, configuration files and certificates shipped with SMT.

7.1 Important Scripts and Tools

  • Filename: smt_scripts.xml
  • ID: smt.scripts

There are two important groups of SMT commands: The smt command and its sub-commands are used for managing the mirroring of updates, registration of clients, and reporting. The systemd smt.target is used for starting, stopping, restarting the SMT service and services that SMT depends on, and for checking their status.

7.1.1 SMT JobQueue

Since SUSE Linux Enterprise version 11, there is a new SMT service called SMT JobQueue for delegating jobs to the registered clients.

To enable JobQueue, the smt-client package needs to be installed on the SMT client. The client then pulls jobs from the server via a cron job (every 3 hours by default). The list of jobs is maintained on the server. Jobs are not pushed directly to the clients and processed immediately: instead, the client asks for them. Therefore, a delay of several hours may occur.

Every job can have its parent job, which sets a dependency. The child job only runs after the parent job successfully finished. Job timing is also possible: a job can have a start time and an expiration time to define its earliest execution time or the time the job will expire. A job may also be persistent. It is run repeatedly with a delay. For example, a patch status job is a persistent job that runs once a day. For each client, a patch status job is automatically generated after it registers successfully against an SMT 11 server. The patchstatus information can be queried with the smt-client command. For already registered clients, you can add patchstatus jobs manually with the smt-job command.

You can edit, list, create, and delete the jobs using the smt-job command-line tool. For more details on smt-job, see Section 7.1.2.3, “smt-job”.

Note
Note: Overriding the Automatic Creation of Patch Status Jobs

When creating a software push or an update job, normally a non-persistent patch status job is added automatically. The parent ID is set to the ID of the new job. To disable this behavior, use the --no-autopatchstatus option.

SMT is not intended to be a system to directly access the clients or to immediately report the results back. It is a long-term maintenance and monitoring system rather than a live interaction tool.

Note
Note: Job Time Lag Limitation

The client normally processes one job at a time, reports back the result, and then asks for the next job. If you create a persistent job with a time offset of only a few seconds, it will be repeated forever and will block other jobs. Therefore, adding jobs with a time offset shorter than one minute is not supported.

7.1.2 /usr/sbin/smt Commands

The key command to manage the SMT is smt (/usr/sbin/smt). The smt command should be used together with various sub-commands described in this section. If the smt command is used alone, it prints a list of all available sub-commands. To get help for individual sub-commands, use smt SUBCOMMAND --help.

The following sub-commands are available:

  • smt-client

  • smt-delete-registration

  • smt-job

  • smt-list-products

  • smt-list-registrations

  • smt-mirror

  • smt-scc-sync

  • smt-register

  • smt-report

  • smt-repos

  • smt-setup-custom-repos

  • smt-staging

  • smt-support

  • smt-sync

There are two syntax types you can use with the smt command: smt followed by a sub-command or a single command consisting of smt followed by the dash and the desired sub-command. For example, it is possible to use either smt mirror or smt-mirror, as both have the same meaning.

Note
Note: Conflicting Commands

Depending on your $PATH environment variable, the SMT smt command (/usr/sbin/smt) may collide with the smt command from the star package (/usr/bin/smt). Either use the absolute path /usr/sbin/smt, create an alias, or set your $PATH accordingly.

Another solution is to always use the smt- SUBCOMMAND syntax.

7.1.2.1 smt-client

The smt-client command shows information about registered clients. The information includes the following:

  • guid

  • host name

  • patch status

  • time stamps of the patch status

  • last contact with the SMT server

The smt-client supports the following options:

--verbose or -v

Shows detailed information about the client. The last contact date is shown as well.

--debug or -d

Enables debugging mode.

--logfile or -L with the parameter LOGFILE

Specifies the file the log will be written to.

--hostname or -h with the parameter HOSTNAME

Lists the entries whose host name begins with HOSTNAME.

--guid or -g with the parameter ID

Lists the entries whose GUID is ID.

--severity or -s with the parameter LEVEL

Filters the result by the patch status information. The value level can be one of packagemanager, security, recommended or optional.

7.1.2.2 smt-delete-registration

The smt-delete-registration command deletes one or more registrations from SMT and SUSE Customer Center. It unregisters machines from the system. The following options are available:

--guid or -g with the parameter ID

Deletes the machine with the guid ID from the system. You can use this option multiple times.

--debug or -d

Enables debugging mode.

7.1.2.3 smt-job

The smt-job script manages jobs for individual SMT clients. You can this command to list, create, edit, and delete jobs. The following options are available:

--list or -l

Lists all client jobs. This is the default if the operation mode switch is omitted.

--verbose or -v with the parameter LEVEL

Shows detailed information about a job or jobs in a list mode. The level value can be a number from 0 to 3. The higher the value, the more verbose the command is.

--create or -c

Creates a new job.

--edit or -e

Edits an existing job.

--delete or -d

Deletes an existing job.

--guid or -g with the parameter ID

Specifies the client's guid. This parameter can be used multiple times to create a job for more than one client.

--jobid or -j with the parameter ID

Specifies the job ID. You need to specify job ID and client's guid when editing or deleting a job, as the same job for multiple clients has the same job ID.

--deleteall or -Aid

Omit either the client's guid or the job ID in the delete operation. The missing parameter will match all respective jobs.

--type or -t with the parameter TYPE

Specifies the job type. The type can be one of patchstatus, softwarepush, update, execute, reboot, wait, eject. On the client, only the following job types are enabled by default: patchstatus, softwarepush and update.

--description DESCRIPTION

Specifies a job description.

--parentID

Specifies the job ID of the parent job. Use it to define a dependency. A job will not be processed until its parent has successfully finished.

--name or -n with the parameter NAME

Specifies a job name.

--persistent

Specifies if a job is persistent. Non-persistent jobs are processed only once, while persistent jobs are processed again and again. Use --timelag to define the time that elapses until the next run.

--finished

Search option for finished jobs.

--targetedtime

Specifies the earliest execution time of a job. Note that the job most likely will not run exactly at that point in time, but probably some minutes or hours after. The reason is that the client polls in a fixed interval for jobs.

--expirestime

Defines when the job will no longer be executed anymore.

--timelagtime

Defines the time interval for persistent jobs.

For a complete list of available options and their explanations, see the manual page of the smt-job command (man smt-job).

7.1.2.3.1 Examples

List all finished jobs:

smt-job --list --finished

Create a softwarepush job that installs xterm and bash on client 12345 and 67890:

smt-job --create -t softwarepush -P xterm -P bash -g 12345 -g 67890

Change the timing for a persistent job with job ID 42 and guid 12345 to run every 6 hours:

smt-job --edit -j 42 -g 12345 --targeted 0000-00-00 --timelag 06:00:00

Delete all jobs with job ID 42:

smt-job --delete -jobid 42 --deleteall

7.1.2.4 smt-list-products

The smt-list-products script lists all software products in the SMT database. The following options are available:

--used or -u

Shows only used products.

--catstat or -c

Shows whether all repositories needed for a product are locally mirrored.

7.1.2.5 smt-list-registrations

The smt-list-registrations script lists all registrations. There are two options available for this command:

--verbose or -v

Shows detailed information about the registered devices.

--format or -f with the parameter FORMAT

Formats the output in the asciitable or csv formats.

7.1.2.6 smt-mirror

The smt-mirror command performs the mirroring procedure and downloads repositories that are set to be mirrored.

You can run the smt-mirror with the following options:

--clean or -c

Removes all files no longer mentioned in the metadata from the mirror. No mirroring occurs before cleanup.

--debug or -d

Enables the debugging mode.

--deepverify

Turns on verifying of all package checksums.

--hardlink SIZE

Searches for duplicate files with a size greater than the size specified in kilobytes. Creates hard links for them.

--directory PATH

Defines the directory to work on. When using this option, the default value configured in the smt.conf configuration file is ignored.

--dbreplfile FILE

Defines a path to the *.xml file to use as database replacement. You can create this file with the smt-scc command.

--logfile or -L with the parameter FILE

Specifies the path to a log file.

7.1.2.7 smt-sync

The smt-sync or smt sync command obtains data from SUSE Customer Center and updates the local SMT database. It can also save SUSE Customer Center data to a directory instead of the SMT database, or read the data from such a directory instead of downloading it from SUSE Customer Center.

For SUSE Linux Enterprise 11 clients, this script automatically determines whether Novell Customer Center or SUSE Customer Center should be used. Then smt-ncc-sync or smt-scc-sync is called. For SUSE Linux Enterprise 12 clients, only smt-scc-sync is supported.

7.1.2.8 smt-scc-sync

The smt scc-sync command obtains data from the SUSE Customer Center and updates the local SMT database. It can also save SUSE Customer Center data to a directory instead of the SMT database, or read SUSE Customer Center data from a directory instead of downloading it from SUSE Customer Center.

You can run the smt-scc-sync with the following options:

--fromdir DIRECTORY

Reads SUSE Customer Center data from a directory instead of downloading it from SUSE Customer Center.

--todir DIRECTORY

Writes SUSE Customer Center data to the specified directory without updating the SMT database.

Tip
Tip: SUSE Manager's Subscription Matching Feature

This data can be used by the subscription matching feature of SUSE Manager, which gives you a detailed overview of your subscription usage. For more information on the subscription matching feature, see https://www.suse.com/documentation/suse-manager-3/book_suma_reference_manual/data/ref_webui_audit_subscription.html

--createdbreplacementfile

Creates a database replacement file for using smt-mirror without database.

--logfile or -L with the parameter LOGFILE

Specifies the path to a log file.

--debug

Enables debugging mode.

7.1.2.9 smt-register

The smt-register or smt register command registers all currently unregistered clients at the SUSE Customer Center. It also registers all clients whose data has changed since the last registration.

The following options are available:

--logfile or -L with the parameter LOGFILE

Specifies the path to a log file.

--debug

Enables debugging mode.

7.1.2.10 smt-report

The smt-report or smt report command generates a subscription report based on local calculation or SUSE Customer Center registrations.

The following options are available:

--mail or -m

Activates mailing the report to the addresses configured with the SMT Server and written in /etc/smt.conf. The report is formatted as tables.

--attach or -a

Appends the report to the e-mails in CSV format. This option should only be used in combination with the --mail option.

--quiet or -q

Suppresses output to STDOUT and runs smt-report in quiet mode.

--csv or -c

Exports the report to multiple files in the CSV format. The first line of each *.csv file consists of the column names. The --csv parameter should only be used in combination with the --file parameter. If the specified file name has the .csv extension, the report is formatted as CSV (as if the --csv parameter was used).

--pdf or -p

Exports the report in the PDF format. Use it only in combination with the -file option.

--xml

Exports the report in the XML format. Use it only in combination with the -file option. For a detailed description of the XML format, see the manual page of the smt-report command.

--file or -F

Exports the report to one or several files. By default, the report is written to a single file formatted as tables. Optionally, the file name or whole path may be specified after the --file filename parameter. If no file name is specified, a default file name containing a time stamp is used. However, SMT does not check if the file or files already exist.

In the CSV mode the report is written to multiple files, therefore the specified file name expands to [PATH/]FILENAME-reportname.extension for every report.

--logfile or -L with the parameter LOGFILE

Specifies path to a log file.

--debug

Enables debugging mode.

7.1.2.11 smt-repos

Use smt-repos (or smt repositories) to list all available repositories and for enabling, disabling, and deleting repositories. The following options are available:

--enable-mirror or -e

Enables repository mirroring.

--disable-mirror or -d

Disables repository mirroring.

--enable-by-prod or -p

Enables repository mirroring by giving product data in the following format: Product[,Version[,Architecture[,Release]]].

--disable-by-prod or -P

Disables repository mirroring by giving product data in the following format: Product[,Version[,Architecture[,Release]]].

--enable-staging or -s

Enables repository staging.

--disable-staging or -S

Disables repository staging.

--only-mirrorable or -m

Lists only repositories that can be mirrored.

--only-enabled or -o

Lists only enabled repositories.

--delete

Lists repositories and deletes them from disk.

--namespace DIRNAME

Deletes the repository in the specified name space.

--verbose or -v

Shows detailed repository information.

7.1.2.12 smt-setup-custom-repos

The smt-setup-custom-repos and smt setup-custom-repos script are designed for setting up custom repositories (repositories not present in the download server) for use with SMT. You can use this script to add a new repository to the SMT database or to delete a repository from the database. The script supports the following options:

--productid PRODUCT_ID

ID of a product the repository belongs to. If a repository should belong to multiple products, use this option multiple times to assign the repository to all relevant products.

--name NAME

The name of the custom repository.

--description DESCRIPTION

The description of the custom repository.

--exturl URL

The URL for the repository to be mirrored from. Only HTTP and HTTPS protocols are supported.

--delete ID

Removes a custom repository with a given ID from the SMT database.

To set up a new repository, use the following command:

smt-setup-custom-repos --productid PRODUCT_ID \
--name NAME --exturl URL

For example:

smt-setup-custom-repos --productid 434 \
--name My_Catalog --exturl http://my.example.com/My_Catalog

To remove a configured repository, use the following command:

smt-setup-custom-repos --delete ID

For example:

smt-setup-custom-repos --delete 1cf336d819e8e5904f4d4b05ee081971a0cc8afc

7.1.2.13 smt-staging

A patch is an update of a package or group of packages. The term update and patch are often interchangeable. With the smt-staging script, you can set up patch filters for update repositories. It can also help you generate both testing repositories and repositories for the production environment.

The first argument of smt-staging is always the command. It must be followed by a repository. The repository can be specified by Name and Target from the table scheme returned by the smt-repos command. Alternatively, it can be specified by its Repository ID which can be obtained by running the command smt-repos -v. The smt-staging script supports the following commands:

listupdates

Lists available patches and their allowed and forbidden status.

allow/forbid

Allows or forbids specified patches.

createrepo

Generates both testing and production repository with allowed patches.

status

Gives information about both testing and production snapshots, and patch counts.

listgroups

Lists staging groups.

There is always one group available with the name default. The default group has the path repo/full, repo/testing and repo. New paths can be specified when creating a new group.

creategroup

Creates a staging group. Required parameters are: group name, testing directory name, and production directory name.

removegroup

Removes a staging group. The group name parameter is required.

The following options apply to any smt-staging command:

--logfile or -Lfile path

Writes log information to the specified file. It is created if it does not already exist.

--debug or -d

Turns on the debugging output and log.

--verbose or -v

Turns more detailed output on.

The following options apply to specific smt-staging commands:

--patch PATCH_ID

Specifies a patch by its ID. You can get a list of available patches with the listupates command. This option can be used multiple times. Use it with the allow, forbid, and listupdates commands. When used with listupdates, the command prints detailed information about the specified patches.

--category CATEGORY

Specifies the patch category. The following categories are available: security, recommended and optional. Use it in combination with the allow, forbid, and listupdates commands.

--all

Allows or forbids all patches in the allow or forbid commands.

--individually

Allows or forbids multiple patches (for example by category) one by one similar to the --patch option used with each of the patches.

--testing

Generates a repository for testing when used in combination with the createrepo command. The repository is generated from the full unfiltered local mirror of the remote repository. It is written into the <MirrorTo>/repo/testing directory, where MirrorTo is the value obtained from smt.conf.

--production

Generates a repository for production when used in combination with the createrepo command. The repository is generated from the testing repository. It is written into the <MirrorTo>/repo directory, where MirrorTo is the value obtained from smt.conf. If the testing repository does not exist, the production repository is generated from the full unfiltered local mirror of the remote repository.

--group GROUP

Specifies on which group the command should work. The default for --group is the name default.

--nohardlink

Prevents creating hard links instead of copying files when creating a repository with the createrepo command. If not specified, hard links are created instead.

--nodesc

Skips patch descriptions and summaries—to save some screen space and make the output more readable.

--sort-by-version

Sorts the listupdates table by patch version. The higher the version, the newer the patch should be.

--sort-by-category

Sorts the listupdates table by patch category.

7.1.2.14 smt-support

The smt-support command manages uploaded support data usually coming from the supportconfig tool. You can forward the data to SUSE, either selectively or in full. This command supports the following options:

--incoming or -i with the parameter DIRECTORY

Specifies the directory where the supportconfig archives are uploaded. You can also set this option with the SMT_INCOMING environment variable. The default SMT_INCOMING directory is /var/spool/smt-support.

--list or -l

Lists the uploaded supportconfig archives in the incoming directory.

--remove or -r with the parameter ARCHIVE

Deletes the specified archive.

--empty or -R

Deletes all archives in the incoming directory.

--upload or -u with the parameter ARCHIVE

Uploads the specified archive to SUSE. If you specify -s, -n, -c, -p, and -e options, the archive is repackaged with contact information.

--uploadall or -U

Uploads all archives in the incoming directory to SUSE.

--srnum or -s with the parameter SR_NUMBER

Specifies the Novell Service Request 12-digit number.

--name or -n with the parameter NAME

Specifies the first and last name of the contact, in quotes.

--company or -c with the parameter COMPANY

Specifies the company name.

--storeid or -d with the parameter ID

Specifies the store ID, if applicable.

--terminalid or -t with the parameter ID

Specifies the terminal ID, if applicable.

--phone or -p with the parameter PHONE

Specifies the phone number of the contact person.

--email or -e with the parameter E-MAIL_ADDRESS

Specifies the e-mail address of the contact.

7.1.3 SMT systemd Commands

You can manage SMT-related services with the standard systemd commands:

systemctl start smt.target

Starts the SMT services.

systemctl stop smt.target

Stops the SMT services.

systemctl status smt.target

Checks the status of the SMT services. Checks whether httpd, Maria DB, and cron are running.

systemctl restart smt.target

Restarts the SMT services.

systemctl try-restart smt.target

Checks whether the SMT services are enabled and if so, restarts them.

You can enable and disable SMT with the YaST SMT Server module.

7.2 SMT Configuration Files

  • Filename: smt_config_files.xml
  • ID: no ID found

The main SMT configuration file is /etc/smt.conf. You can set most of the options with the YaST SMT Server module. Another important configuration file is /etc/smt.d/smt-cron.conf, which contains parameters for commands launched as SMT scheduled jobs.

7.2.1 /etc/smt.conf

The /etc/smt.conf file has several sections. The [NU] section contains the update credentials and URL. The [DB] section contains the configuration of the Maria DB database for SMT. The [LOCAL] section includes other configuration data. The [REPORT] section contains the configuration of SMT reports.

Warning
Warning: Passwords in Clear Text

The /etc/smt.conf file contains passwords in clear text. Its default permissions (640, root, wwwrun) make its content easily accessible with scripts running on the Apache server. Be careful with running other software on the SMT Apache server. The best policy is to use this server only for SMT.

7.2.1.1 [NU] Section of /etc/smt.conf

The following options are available in the [NU] section:

NUUrl

URL of the update service. Usually it should contain the https://updates.suse.com/ URL.

NURegUrl

URL of the update registration service. It is used by smt-sync. If this option is missing, the URL from /etc/SUSEConnect is used as a fallback.

NUUser

NUUser should contain the user name for update service. For information about getting organization credentials, see Section 3.1, “Mirroring Credentials”. You can set this value with the SMT Server.

NUPass

NUPass is the password for the user defined in NUUser. For information about getting organization credentials, see Section 3.1, “Mirroring Credentials”. You can set this value with the SMT Server.

ApiType

ApiType is the type of service SMT uses; it can be either NCC for Novell Customer Center or SCC for SUSE Customer Center. The only supported value for SMT 12 is SCC.

7.2.1.2 [DB] Section of /etc/smt.conf

The three options defined in the [DB] section are used for configuring the database for SMT. Currently, only Maria DB is supported by SMT.

config

The first parameter of the DBI->connect Perl method used for connection to the Maria DB database. The value should be in the form

dbi:mysql:database=SMT;host=LOCALHOST

where SMT is the name of the database and LOCALHOST is the host name of the database server.

user

The user for the database. The default value is smt.

pass

The password for the database user. You can set the password with the YaST SMT Server module.

7.2.1.3 [LOCAL] Section of /etc/smt.conf

The following options are available in the [LOCAL] section:

url

The base URL of the SMT server which is used to construct URLs of the repositories available on the server. This value should be set by YaST automatically during installation. The format of this option should be: https://server.domain.tld/.

You can change the URL manually. For example, the administrator may choose to use the http:// scheme instead of https:// for performance reasons. Another reason may be using an alias (configured with CNAME in DNS) instead of the host name of the server. For example, http://smt.domain.tld/ instead of http://server1.domain.tld/.

nccEmail

E-mail address used for registration at the SUSE Customer Center. The SMT administrator can set this value with the YaST SMT Server module.

MirrorTo

Determines the path to mirror to.

MirrorAll

If the MirrorAll option is set to true, the smt-sync script will set all repositories that can be mirrored to be mirrored (DOMIRROR flag).

MirrorSRC

If the MirrorSRC option is set to true, source RPM packages are mirrored.

Note
Note: Default Value Changed with SMT 11 SP2

With SMT 11 SP2, the preset default value was changed to false. If you also want SMT to mirror source RPM packages on new installations, set MirrorSRC to true.

Upgraded systems are not affected.

forwardRegistration

For SMT 11, this option determined whether the clients registered at SMT should be registered at Novell Customer Center, too. This option does not work with SUSE Customer Center yet.

rndRegister

Specify a delay in seconds before the clients are registered at SUSE Customer Center. The value is a random number between 0 and 450, generated by the YaST SMT Server module. The purpose of this random delay is to prevent a high load on the SUSE Customer Center server that would occur if all smt-register cron jobs connected at the same time.

mirror_preunlock_hook

Specify the path to the script that will be run before the smt-mirror script removes its lock.

mirror_postunlock_hook

Specify the path to the script that will be run after the smt-mirror script removes its lock.

HTTPProxy

If you do not want to use global proxy settings, specify the proxy to be used for HTTP connection here. Use the following form: http://PROXY.example.com:3128.

If the proxy settings are not configured in /etc/smt.conf, the global proxy settings configured in /etc/syconfig/proxy are used. You can configure the global proxy settings with the YaST Proxy module.

HTTPSProxy

If you do not want to use global proxy settings, specify the proxy to be used for HTTPS connection here. Use the form: https://PROXY.example.com:3128.

If the proxy settings are not configured in /etc/smt.conf, the global proxy settings configured in /etc/syconfig/proxy are used. You can configure the global proxy settings with the YaST Proxy module.

ProxyUser

If your proxy requires authentication, specify a user name and password here, using the USERNAME:PASSWORD format.

If the proxy settings are not configured in /etc/smt.conf, the global proxy settings configured in /etc/syconfig/proxy are used. You can configure the global proxy settings with the YaST Proxy module.

Tip
Tip: Global User Authentication Setting

If you configure the global proxy settings with YaST, manually copy /root/.curlrc to the home directory of the smt. Adjust the permissions with the following commands as root:

cp /root/.curlrc /var/lib/smt/
chown smt:www /var/lib/smt/.curlrc
requiredAuthType

Specify an authentication type to access the repository. There are three possible types:

  • none - no authentication is required. This is the default value.

  • lazy - only user name and password are checked. A valid user can access all repositories.

  • strict - checks also if the user has access to the repository.

smtUser

Specify a user name of a Unix user under which all smt commands will run.

signingKeyID

Specify the ID of the GPG key to sign modified repositories. The user specified under smtUser needs to have access to the key. If this option is not set, the modified repositories will be unsigned.

7.2.1.4 [REST] Section of /etc/smt.conf

The following options are available in the [REST] section:

enableRESTAdminAccess

If set to 1, turns administrative access to the SMT RESTService on. Default value is 0.

RESTAdminUser

Specify the user name that the REST-Admin uses to log in. Default value is RESTroot.

RESTAdminPassword

Specify the password for the REST-Admin user. The option has no default value. An empty password is invalid.

7.2.1.5 [JOBQUEUE] Section of /etc/smt.conf

The following options are available in the [JOBQUEUE] section:

maxFinishedJobAge

Specify the maximum age of finished non-persistent jobs in days. Default value is 8.

jobStatusIsSuccess

Specify a comma separated list of JobQueue status IDs that should be interpreted as successful. For more information about possible status IDs, see smt-job --help. Leaving this option empty is interpreted as default (1,4).

7.2.1.6 [REPORT] Section of /etc/smt.conf

The following options are available in the [REPORT] section:

reportEmail

A comma separated list of e-mail addresses to send SMT status reports to. You can set this list with the YaST SMT Server module.

reportEmailFrom

From field of report e-mails. If not set, the default root@HOSTNAME.DOMAINNAME will be used.

mailServer

Relay mail server. If empty, e-mails are sent directly.

mailServerPort

Port of the relay mail server set in mailServer.

mailServerUser

User name for authentication to the mail server set in mailServer.

mailServerPassword

Password for authentication to the mail server set in mailServer.

7.2.1.7 Example /etc/smt.conf

Example 7.1: smt.conf
[NU]
NUUrl=https://updates.suse.com/
NURegUrl=https://scc.suse.com/connect
NUUser = exampleuser
NUPass = examplepassword
ApiType = SCC

[DB]
config = dbi:mysql:database=smt;host=localhost
user = smt
pass = smt

[LOCAL]
# Default should be http://server.domain.top/
url = http://smt.example.com/
# This email address is used for registration at SCC
nccEmail = exampleuser@example.com
MirrorTo = /srv/www/htdocs
MirrorAll = false
MirrorSRC = false
forwardRegistration = true
rndRegister = 127
# The hook script that should be called before the smt-mirror script removes its lock
mirror_preunlock_hook =
# The hook script that should be called after the smt-mirror script removed its lock
mirror_postunlock_hook =
# specify proxy settings here, if you do not want to use the global proxy settings
# If you leave these options empty the global options are used.
#
# specify which proxy you want to use for HTTP connection
# in the form http://proxy.example.com:3128
HTTPProxy =
# specify which proxy you want to use for HTTPS connection
# in the form http://proxy.example.com:3128
HTTPSProxy =
# specify username and password if your proxy requires authentication
# in the form username:password
ProxyUser =
#
# require authentication to access the repository?
# Three possible authtypes can be configured here
# 1) none   : no authentication required (default)
# 2) lazy   : check only username and password. A valid user has access to all repositories
# 3) strict : check also if this user has access to the repository.
#
requiredAuthType = none
#
# the smt commands should run with this unix user
#
smtUser = smt
#
# ID of the GPG key to be used to sign modified (filtered) repositories.
# The key must be accessible by the user who runs SMT, i.e. the user specified
# in the 'smtUser' configuration option.
#
# If empty, the modified repositories will be unsigned.
#
signingKeyID =
#
# This string is sent in HTTP requests as UserAgent.
# If the key UserAgent does not exist, a default is used.
# If UserAgent is empty, no UserAgent string is set.
#
#UserAgent=
# Organization credentials for this SMT server.
# These are currently only used to get list of all available repositories
# from https://your.smt.url/repo/repoindex.xml
# Note: if authenticated as a client machine instead of these mirrorUser,
# the above URL returns only repositories relevant for that client.
mirrorUser =
mirrorPassword =

[REST]
# Enable administrative access to the SMT RESTService by setting enableRESTAdminAccess=1
# default: 0
enableRESTAdminAccess = 0
# Define the username the REST-Admin uses for login
# default: RESTroot
RESTAdminUser = RESTroot
# Define the password for the REST-Admin (note: empty password is invalid)
# default: <empty>
RESTAdminPassword =

[JOBQUEUE]
# maximum age of finished (non-persistent) jobs in days
# default: 8
maxFinishedJobAge = 8
# comma separated list of JobQueue status IDs that should be interpreted as successful
# See smt-job --help for more information about possible Status IDs
# Please note: An empty string will be interpreted as default (1,4).
# default: 1,4
# useful:  1,4,6
jobStatusIsSuccess = 1,4

[REPORT]
# comma separated list of eMail addresses where the status reports will be sent to
reportEmail = exampleuser@example.com
# from field of report mails - if empty it defaults to "root@<hostname>.<domainname>"
reportEmailFrom =
# relay mail server - leave empty if mail should be sent directly
mailServer =
mailServerPort =
# mail server authentication - leave empty if not required
mailServerUser =
mailServerPassword =

7.2.2 /etc/smt.d/smt-cron.conf

The /etc/smt.d/smt-cron.conf configuration file contains options of the SMT commands launched as SMT scheduled jobs set with YaST (see Section 2.5, “Setting the SMT Job Schedule with YaST”). Cron is used to launch these scheduled jobs. The cron table is located in the /etc/cron.d/novell.com-smt file.

SCC_SYNC_PARAMS

Contains parameters of the smt scc-sync command, if called as part of an SMT scheduled job via cron. The default value is "-L /var/log/smt/smt-sync.log --mail".

MIRROR_PARAMS

Contains parameters of the smt mirror command, if called as part of an SMT scheduled job via cron. The default value is "-L /var/log/smt/smt-mirror.log --mail" .

REGISTER_PARAMS

Contains parameters of the smt register command, if called as part of an SMT scheduled job via cron. The default value is "-r -L /var/log/smt/smt-register.log --mail" .

REPORT_PARAMS

Contains parameters of the smt report command, if called as part of an SMT scheduled job via cron. The default value is "--mail --attach -L /var/log/smt/smt-report.log" .

JOBQUEUECLEANUP_PARAMS

Contains parameters for smt jobqueue cleanup, if called as a part of an SMT scheduled job via cron. The default value is "--mail -L /var/log/smt/smt-jobqueuecleanup.log".

7.3 Server Certificates

  • Filename: smt_certificates.xml
  • ID: smt.tools.cert

For communication between the SMT server and client machines, the encrypted HTTPS protocol is used, requiring a server certificate. If the certificate is not available, or if clients are not configured to use the certificate, the communication between server and clients will fail.

Every client must be able to verify the server certificate by trusting the CA (certificate authority) certificate that signed the server certificate. Therefore, the SMT server provides a copy of the CA at /srv/www/htdocs/smt.crt. This CA can be downloaded from every client via the URL http://FQDN/smt.crt. The copy is created by the /usr/lib/SMT/bin/smt-maintenance script. Whenever SMT is started with systemctl start smt.target, it checks the certificate. If a new CA certificate exists, it is copied again. Therefore, whenever the CA certificate is missing or changed, restart SMT using the systemctl restart smt.target command.

When the SMT Server module applies configuration changes, it checks for the existence of the common server certificate. If the certificate does not exist, YaST asks whether the certificate should be created. If the user confirms, the YaST CA Management module is started.

7.3.1 Certificate Expiration

The common server certificate SMT uses is valid for one year. After that time, a new certificate is needed. Either generate a new certificate using YaST CA Management module or import a new certificate using the YaST Common Server Certificate module. Both options are described in the following sections.

As long as the same CA certificate is used, there is no need to update certificates on the client machines. The generated CA certificate is valid for 10 years.

7.3.2 Creating a New Common Server Certificate

To create a new common server certificate with YaST, proceed as follows:

  1. Start YaST and select Security and Users › CA Management. Alternatively, start the YaST CA Management module from a command line by entering yast2 ca_mgm as root.

  2. Select the required CA and click Enter CA.

  3. Enter the password if entering a CA for the first time. YaST displays the CA key information in the Description tab.

  4. Click the Certificates tab (see Figure 7.1, “Certificates of a CA”) and select Add › Add Server Certificate.

    Certificates of a CA
    Figure 7.1: Certificates of a CA
  5. Enter the fully qualified domain name of the server as Common Name. Add a valid e-mail address of the server administrator. Other fields, such as Organization, Organizational Unit, Locality, and State are optional. Click Next to proceed.

    Important
    Important: Host Name in Server Certificate

    The server certificate must contain the correct host name. If the client requests server https://some.hostname/, then some.hostname must be part of the certificate. The host name must either be used as the Common Name, see Step 5, or as the Subject Alternative Name, see Step 7: DNS:some.hostname and IP:<ipaddress>.

  6. Enter a Password for the private key of the certificate and re-enter it in the next field to verify it.

  7. If you want to define a Subject Alternative Name, click Advanced Options, select Subject Alternative Name from the list and click Add.

    Important
    Important: Subject Alternative Name

    If Subject Alternative Name be in the server certificate, then it needs to contain the DNS entry. If Subject Alternative Name is present, the Common Name (CN) is not checked anymore.

  8. If you want to keep the default values for the other options, like Key Length and Valid Period, click Next. An overview of the certificate to be created is shown.

  9. Click Create to generate the certificate.

  10. To export the new certificate as the common server certificate, select it in the Certificates tab and select Export › Export as Common Server Certificate.

  11. After having created a new certificate, restart SMT using the systemctl restart smt.target command. Restarting SMT ensures that the new certificate is copied from /etc/ssl/certs/YaST-CA.pem to /srv/www/htdocs/smt.crt, the copy SMT uses. Restarting SMT also restarts the Web server.

For detailed information about managing certification and further usage of the YaST CA Management module and the Common Server Certificate module, refer to the Security Guide. It si available from https://www.suse.com/documentation/sles-12.

7.3.3 Importing a Common Server Certificate

You can import an own common server certificate from a file. The certificate to be imported needs to be in the PKCS12 format with CA chain. Common server certificates can be imported with the YaST Common Server Certificate module.

To import an own certificate with YaST, proceed as follows:

  1. Start YaST and select Security and Users › Common Server Certificate. Alternatively, start the YaST Common Server Certificate module from the command line by entering yast2 common_cert as root.

    The description of the currently used common server certificate is shown in the dialog that opens.

  2. Click Import and select the file containing the certificate to be imported. Specify the certificate password in the Password field.

  3. Click Next. If the certificate is successfully imported, close YaST with Finish.

  4. After having created a new certificate, restart SMT using the systemctl restart smt.target command. Restarting SMT ensures that the new certificate is copied from /etc/ssl/certs/YaST-CA.pem to /srv/www/htdocs/smt.crt, the copy SMT uses. Restarting SMT also restarts the Web server.

7.3.4 Synchronizing Time between SMT Server and Clients

The synchronization of time between the SMT server and clients is highly recommended. Each server certificate has a validity period. If the client happens to be set to a time outside of this period, the certificate validation on the client side fails.

Therefore, it is advisable to keep the time on the server and clients synchronized. You can easily synchronize the time using NTP (network time protocol). Use yast2 ntp-client to configure an NTP client. Find detailed information about NTP in the Administration Guide.

8 Configuring Clients to Use SMT

  • Filename: smt_client.xml
  • ID: smt.client

Any machine running SUSE Linux Enterprise 10 SP4, 11 SP1 or later, or any version of SUSE Linux Enterprise 12 can be configured to register against SMT and download software updates from there, instead of communicating directly with SUSE Customer Center or Novell Customer Center.

If your network includes an SMT server to provide a local update source, you need to equip the client with the server's URL. As client and server communicate via the HTTPS protocol during registration, you also need to make sure the client trusts the server's certificate. In case you set up your SMT server to use the default server certificate, the CA certificate will be available on the SMT server at http://FQDN/smt.crt .

If the certificate is not issued by a well-trusted authority, the registration process will import the certificate from the URL specified as regcert parameter (SUSE Linux Enterprise Server 10 and 11). For SLE 12, the certificate will be downloaded automatically from SMT. In this case, the client displays the new certificate details (its fingerprint), and you need to accept the certificate.

There are several ways to provide the registration information and to configure the client machine to use SMT:

  1. Provide the required information via kernel parameters at boot time (Section 8.1, “Using Kernel Parameters to Access an SMT Server”).

  2. Configure the clients using an AutoYaST profile (Section 8.2, “Configuring Clients with AutoYaST Profile”).

  3. Use the clientSetup4SMT.sh script (Section 8.3, “Configuring Clients with the clientSetup4SMT.sh Script in SLE 11 and 12”). This script can be run on a client to make it register against a specified SMT server.

  4. In SUSE Linux Enterprise 11 and 12, you can set the SMT server URL with the YaST registration module during installation (Section 8.4, “Configuring Clients with YaST”).

These methods are described in the following sections.

8.1 Using Kernel Parameters to Access an SMT Server

Important
Important: regcert Parameter Support

Note that the regcert kernel boot parameter is supported for SLE 10 and 11. It is not supported from SLE 12.

Any client can be configured to use SMT by providing the following kernel parameters during machine boot: regurl and regcert. The first parameter is mandatory, the latter is optional.

Warning
Warning: Beware of Typing Errors

Make sure the values you enter are correct. If regurl has not been specified correctly, the registration of the update source will fail.

If an invalid value for regcert has been entered, you will be prompted for a local path to the certificate. In case regcert is not specified, it will default to http://FQDN/smt.crt with FQDN being the name of the SMT server.

regurl

URL of the SMT server.

For SLE 11 and older clients, the URL needs to be in the following format: https://FQDN/center/regsvc/ with FQDN being the fully qualified host name of the SMT server. It must be identical to the FQDN of the server certificate used on the SMT server. Example:

regurl=https://smt.example.com/center/regsvc/

For SLE 12 clients, the URL needs to be in the following format: https://FQDN/connect/ with FQDN being the fully qualified host name of the SMT server. It must be identical to the FQDN of the server certificate used on the SMT server. Example:

regurl=https://smt.example.com/connect/
regcert

Location of the SMT server's CA certificate. Specify one of the following locations:

URL

Remote location (HTTP, HTTPS, or FTP) from which the certificate can be downloaded. Example:

regcert=http://smt.example.com/smt.crt
Floppy

Specifies a location on a floppy. The floppy needs to be inserted at boot time—you will not be prompted to insert it if it is missing. The value needs to start with the string floppy, followed by the path to the certificate. Example:

regcert=floppy/smt/smt-ca.crt
Local Path

Absolute path to the certificate on the local machine. Example:

regcert=/data/inst/smt/smt-ca.cert
Interactive

Use ask to open a pop-up menu during installation where you can specify the path to the certificate. Do not use this option with AutoYaST. Example:

regcert=ask
Deactivate Certificate Installation

Use done if either the certificate will be installed by an add-on product, or if you are using a certificate issued by an official certificate authority. Example:

regcert=done
Warning
Warning: Change of SMT Server Certificate

If the SMT server gets a new certificate from an untrusted CA, the clients need to retrieve the new CA certificate file.

On SLE 10 and 11, this is done automatically with the registration process in the following cases:

  • If a URL was used at installation time to retrieve the certificate.

  • If the regcert parameter was omitted and thus the default URL is used.

If the certificate was loaded using any other method, such as floppy or local path, the CA certificate will not be updated.

On SUSE Linux Enterprise Server 12, after the certificate has changed, YaST displays a dialog for importing a new certificate. If you confirm importing the new certificate, the old one is replaced with the new one.

8.2 Configuring Clients with AutoYaST Profile

Clients can be configured to register with SMT server via AutoYaST profile. For general information about creating AutoYaST profiles and preparing automatic installation, refer to the AutoYaST Guide. In this section, only SMT specific configuration is described.

To configure SMT specific data using AutoYaST, follow the steps for the relevant version of SMT client.

8.2.1 Configuring SUSE Linux Enterprise 11 Clients

  1. As root, start YaST and select Miscellaneous › Autoinstallation to start the graphical AutoYaST front-end.

    From a command line, you can start the graphical AutoYaST front-end with the yast2 autoyast command.

  2. Open an existing profile using File › Open, create a profile based on the current system's configuration using Tools › Create Reference Profile, or work with an empty profile.

  3. Select Software › Novell Customer Center Configuration. An overview of the current configuration is shown.

  4. Click Configure.

  5. Set the URL of the SMT Server and, optionally, the location of the SMT Certificate. The possible values are the same as for the kernel parameters regurl and regcert (see Section 8.1, “Using Kernel Parameters to Access an SMT Server”). The only exception is that the ask value for regcert does not work in AutoYaST, because it requires user interaction. If using it, the registration process will be skipped.

  6. Perform all other configuration needed for the systems to be deployed.

  7. Select File › Save As and enter a file name for the profile, such as autoinst.xml.

8.2.2 Configuring SUSE Linux Enterprise 12 Clients

  1. As root, start YaST and select Miscellaneous › Autoinstallation to start the graphical AutoYaST front-end.

    From a command line, you can start the graphical AutoYaST front-end with the yast2 autoyast command.

  2. Open an existing profile using File › Open, create a profile based on the current system's configuration using Tools › Create Reference Profile, or work with an empty profile.

  3. Select Software › Product Registration. An overview of the current configuration is shown.

  4. Click Edit.

  5. Check Register the Product, set the URL of the SMT server in Use Specific Server URL Instead of the Default, and you can set the Optional SSL Server Certificate URL. The possible values for the server URL are the same as for the kernel parameter regurl. For the SSL certificate location, you can use either HTTP or HTTPS based URLs.

  6. Perform all other configuration needed for the systems to be deployed, then click Finish to return to the main screen.

  7. Select File › Save As and enter a file name for the profile, such as autoinst.xml.

8.3 Configuring Clients with the clientSetup4SMT.sh Script in SLE 11 and 12

In SLE 11 and 12, the /usr/share/doc/packages/smt/clientSetup4SMT.sh script is provided together with SMT. This script allows you to configure a client machine to use an SMT server. It can also be used to reconfigure an existing client to use a different SMT server.

Note
Note: Installation of wget

The script clientSetup4SMT.sh itself uses wget, so wget must be installed on the client.

Important
Important: Upgrade clientSetup4SMT.sh

If you migrated your client OS from an older SUSE Linux Enterprise, check if the version of the clientSetup4SMT.sh script on your host is up to date. clientSetup4SMT.sh from older versions of SMT cannot manage SMT 12 clients. If you apply software patches regularly on your SMT server, you can always find the latest version of clientSetup4SMT.sh at <SMT_HOSTNAME>/repo/tools/clientSetup4SMT.sh.

To configure a client machine to use SMT with the clientSetup4SMT.sh script, follow these steps:

  1. Copy the clientSetup4SMT.sh script from your SMT server to the client machine. The script is available at <SMT_HOSTNAME>/repo/tools/clientSetup4SMT.sh and /srv/www/htdocs/repo/tools/clientSetup4SMT.sh. You can download it with a browser, using wget, or by another means, such as with scp.

  2. As root, execute the script on the client machine. The script can be executed in two ways. In the first case, the script name is followed by the registration URL. For example:

    ./clientSetup4SMT.sh https://smt.example.com/center/regsvc

    In the second case, the script uses the --host option followed by the host name of the SMT server, and --regcert followed by the URL of the SSL certificate; for example:

    ./clientSetup4SMT.sh --host smt.example.com \
      --regcert http://smt.example.com/certs/smt.crt

    In this case, without any namespace specified, the client will be configured to use the default production repositories. If --namespace GROUPNAME is specified, the client will use that staging group.

  3. The script downloads the server's CA certificate. Accept it by pressing Y.

  4. The script performs all necessary modifications on the client. However, the registration itself is not performed by the script.

  5. The script downloads and asks to accept additional GPG keys to sign repositories with.

  6. On SLE 11, perform the registration by executing suse_register or running the yast2 inst_suse_register module on the client.

    On SLE 12, perform the registration by executing

    SUSEConnect -p PRODUCT_NAME --url https://smt.example.org

    or running the yast2 registration (SUSE Linux Enterprise Server 12 SP1 and newer) or yast2 scc (SUSE Linux Enterprise Server 12) module on the client.

The clientSetup4SMT.sh script works with SUSE Linux Enterprise 10 SP2 and later Service Packs, SLE 11, and SLE 12 systems.

This script is also provided for download. You can get it by running

wget http://smt.example.com/repo/tools/clientSetup4SMT.sh
Important
Important: Extension and Module Registration in SUSE Linux Enterprise 12

When registering an existing system against SMT 12—both on the command line and using YaST—you need to register additional extensions and modules separately, one by one. This applies both to already installed extensions and to extensions that you plan to install.

8.3.1 Problems Downloading GPG Keys from the Server

The apache2-example-pages package includes a robots.txt file. The file is installed into the Apache2 document root directory, and controls how clients can access files from the Web server. If this package is installed on the server, clientSetup4SMT.sh fails to download the keys stored under /repo/keys.

You can solve this problem by either editing robots.txt, or uninstalling the apache2-example-pages package.

If you choose to edit the robots.txt file, add before the Disallow: / statement:

Allow: /repo/keys

8.4 Configuring Clients with YaST

8.4.1 Configuring Clients with YaST in SLE 11

To configure a client to perform the registration against an SMT server use the YaST registration module (yast2 inst_suse_register).

Click Advanced › Local Registration Server and enter the name of the SMT server plus the path to the registration internals (/center/regsvc/), for example:

https://smt.example.com/center/regsvc/

After confirmation the certificate is loaded and the user is asked to accept it. Then continue.

Warning
Warning: Staging Groups Registration

If a staging group is used, make sure that settings in /etc/suseRegister.conf are done accordingly. If not already done, modify the register= parameter and append &namespace=NAMESPACE. For more information about staging groups, see Section 4.3, “Staging Repositories”.

Alternatively, use the clientSetup4SMT.sh script (see Section 8.3, “Configuring Clients with the clientSetup4SMT.sh Script in SLE 11 and 12”).

8.4.2 Configuring Clients with YaST in SLE 12

To configure a client to perform the registration against an SMT server use the YaST Product Registration module yast2 registration (SUSE Linux Enterprise Server 12 SP1 or newer) or yast2 scc (SUSE Linux Enterprise Server 12).

On the client, the credentials are not necessary and you may leave the relevant fields empty. Click Local Registration Server and enter its URL. Then click Next until the exit from the module.

8.5 Registering SLE11 Clients against SMT Test Environment

To configure a client to register against the test environment instead of the production environment, modify /etc/suseRegister.conf on the client machine by setting:

register = command=register&namespace=testing

For more information about using SMT with a test environment, see Section 3.5, “Using the Test Environment”.

8.6 Registering SLE12 Clients against SMT Test Environment

To configure a client to register against the test environment instead of the production environment, modify /etc/SUSEConnect on the client machine by setting:

namespace: testing

For more information about using SMT with a test environment, see Section 3.5, “Using the Test Environment”.

8.7 Listing Accessible Repositories

To retrieve the accessible repositories for a client, download repo/repoindex.xml from the SMT server with the client's credentials. The credentials are stored in /etc/zypp/credentials.d/SCCcredentials (SUSE Linux Enterprise Server 12) or /etc/zypp/credentials.d/NCCcredentials (SUSE Linux Enterprise Server 11) on the client machine. Using wget, the command for testing could be as follows:

wget https://USER:PASS@smt.example.com/repo/repoindex.xml

repoindex.xml returns the complete repository list as they come from the vendor. If a repository is marked for staging, repoindex.xml lists the repository in the full namespace (repos/full/$RCE).

To get a list of all repositories available on the SMT server, use the credentials specified in the [LOCAL] section of /etc/smt.conf on the server as mirrorUser and mirrorPassword.

8.8 Online Migration of SUSE Linux Enterprise Clients

SUSE Linux Enterprise clients registered against SMT can be migrated online to the latest service pack of the same major release the same way as clients registered against SUSE Customer Center or Novell Customer Center. Before starting the migration, make sure that SMT is configured to provide the correct version of repositories to which you need the clients to migrate.

For detailed information on online migration, see https://www.suse.com/documentation/sles11/book_sle_deployment/data/cha_update_sle.html for SUSE Linux Enterprise 11 clients, or Chapter 19, Upgrading SUSE Linux Enterprise for SUSE Linux Enterprise 12 clients.

8.9 How to Update Red Hat Enterprise Linux with SMT

SMT enables customers that possess the required entitlements to mirror updates for Red Hat Enterprise Linux (RHEL). Refer to http://www.suse.com/products/expandedsupport/ for details on SUSE Linux Enterprise Server Subscription with Expanded Support. This section discusses the actions required to configure the SMT server and clients (RHEL servers) for this solution.

Note
Note: SUSE Linux Enterprise Server 10

Configuring RHEL client with Subscription Management Tool for SUSE Linux Enterprise (SMT 1.0) running SUSE Linux Enterprise Server 10 is slightly different. For more information, see How to update Red Hat Enterprise Linux with SMT.

8.9.1 How to Prepare SMT Server for Mirroring and Publishing Updates for RHEL

  1. Install SUSE Linux Enterprise Server (SLES) with the SMT packages as per the documentation on the respective products.

  2. During SMT setup, use organization credentials that have access to Novell-provided RHEL update repositories.

  3. Verify that the organization credentials have access to download updates for the Red Hat products with

    smt-repos -m | grep RES
  4. Enable mirroring of the RHEL update repositories for the desired architecture(s):

    smt-repos -e REPO-NAME ARCHITECTURE
  5. Mirror the updates and log verbose output:

    smt-mirror -d -L /var/log/smt/smt-mirror.log

    The updates for RHEL will also be mirrored automatically as part of the default nightly SMT mirroring cron job. When the mirror process of the repositories for your RHEL products has completed, the updates are available via

    http://smt-server.your-domain.top/repo/$RCE/REPOSITORY_NAME/ARCHITECTURE/
  6. To enable GPG checking of the repositories, the key used to sign the repositories needs to be made available to the RHEL clients. This key is now available in the res-signingkeys package, which is included in the SMT 11 installation source.

    • Install the res-signingkeys package with the command

      zypper in -y res-signingkeys
    • The installation of the package stores the key file as /srv/www/htdocs/repo/keys/res-signingkeys.key.

    • Now the key is available to the clients and can be imported into their RPM database as described later.

8.9.2 How to Configure the YUM Client on RHEL 5.2 to Receive Updates from SMT

  1. Import the repository signing key downloaded above into the local RPM database with

    rpm --import http://smt.example.com/repo/keys/res-signingkeys.key
  2. Create a file in /etc/yum.repos.d/ and name it RES5.repo.

  3. Edit the file and enter the repository data, and point to the repository on the SMT server as follows:

    [smt]
    name=SMT repository
    baseurl=http://smt.example.com/repo/$RCE/REPOSITORY_NAME/ARCHITECTURE/
    enabled=1
    gpgcheck=1

    Example of base URL:

    http://smt.mycompany.com/repo/$RCE/RES5/i386/
  4. Save the file.

  5. Disable standard Red Hat repositories by setting

    enabled=0

    in the repository entries in other files in /etc/yum.repos.d/ (if any are enabled).

    Both YUM and the update notification applet should work correctly now and notify of available updates when applicable. You may need to restart the applet.

8.9.3 How to Configure the UP2DATE Client on RHEL 3.9 and 4.7 to Receive Updates from SMT

  1. Import the repository signing key downloaded above into the local RPM database with

    rpm --import http://smt.example.com/repo/keys/res-signingkeys.key
  2. Edit the file /etc/sysconfig/rhn/sources and make the following changes:

  3. Comment out any lines starting with up2date.

    Normally, there will be a line that says "up2date default".

  4. Add an entry pointing to the SMT repository (all in one line):

    yum REPO_NAME http://smt.example.com/repo/$RCE/REPOSITORY_NAME/ARCHITECTURE/

    where repo-name should be set to RES3 for 3.9 and RES4 for 4.7.

  5. Save the file.

Both up2date and the update notification applet should work correctly now, pointing to the SMT repository and indicating updates when available. In case of trouble, try to restart the applet.

To ensure correct reporting of the Red Hat Enterprise systems in SUSE Customer Center, they need to be registered against your SMT server. For this a special suseRegisterRES package is provided through the RES* repositories and it should be installed, configured and executed as described below.

8.9.4 How to Register RHEL 5.2 against SMT

  1. Install the suseRegisterRES package.

    yum install suseRegisterRES
    Note
    Note: Additional Packages

    You may need to install the perl-Crypt-SSLeay and perl-XML-Parser packages from the original RHEL media.

  2. Copy the SMT certificate to the system:

    wget http://smt.example.com/smt.crt
    cat smt.crt >> /etc/pki/tls/cert.pem
  3. Edit /etc/suseRegister.conf to point to SMT by changing the URL value to

    url: https://smt.example.com/center/regsvc/

    or (for SUSE Customer Center)

    url = https://smt.example.com/connect/
  4. Register the system:

    suse_register

8.9.5 How to Register RHEL 4.7 and RHEL 3.9 against SMT

  1. Install the suseRegisterRES package:

    up2date --get suseRegisterRES
    up2date --get perl-XML-Writer
    rpm -ivh /var/spool/up2date/suseRegisterRES*.rpm /var/spool/up2date/perl-XML-Writer-0*.rpm
    Note
    Note: Additional Packages

    You may need to install the perl-Crypt-SSLeay and perl-XML-Parser packages from the original RHEL media.

  2. Copy the SMT certificate to the system:

    wget http://smt.example.com/smt.crt
    cat smt.crt >> /usr/share/ssl/cert.pem
  3. Edit /etc/suseRegister.conf to point to SMT by changing the URL value to

    url = https://smt.example.com/center/regsvc/

    or (for SUSE Customer Center)

    url = https://smt.example.com/connect/
  4. Register the system:

    suse_register

9 Advanced Topics

  • Filename: smt_advanced.xml
  • ID: smt.advanced

This chapter covers usage scenarios beyond the regular workflow to give you more control over your SMT server.

9.1 Backup of the SMT Server

Creating backups of the SMT server regularly can help restore it quickly and reliably if the server fails.

There are three main parts on the SMT server to back up:

  • Configuration files

  • Package repositories

  • The database

9.1.1 Configuration Files and Repositories

The SMT server configuration is stored in the /etc/smt.conf file and files in the /etc/smt.d directory.

As SMT depends on the services provided by the Apache Web server and Maria DB database engine, you need to back up their configuration files as well. Apache configuration files are located in the /etc/apache2 directory, while configuration of Maria DB is stored in /etc/my.cnf, /etc/mysqlaccess.conf, and files in the /etc/my.cnf.d directory.

Package repositories are stored in the /srv/www/htdocs/repo directory. While you can normally mirror the repositories on the restored server from the update server as well, the download can take a long time. Therefore backing up the repositories can save you time and bandwidth. Moreover, backing up the repositories is necessary if you are using repository staging and want to restore the snapshots of the repositories (see Section 3.6, “Testing and Filtering Update Repositories with Staging”).

Warning
Warning: Size of the Repositories

The software repositories can be significant in size, and you will need to transfer them from the update server.

Use your preferred tool to back up the configuration and repository files.

9.1.2 The Database

SMT uses the Maria DB database to store information about clients, registrations, machine data, which repositories are enabled for mirroring, and custom repositories. Unlike the configuration files and repositories, the database information cannot be recovered without a valid backup.

To back up the SMT database, you can for example create a cron job that performs an SQL dump into a plain text file:

mysqldump -u root -p SMT_DB_PASSWORD smt > /BACKUP_DIR/smt-db-backup.sql

Then add the resulting file to your regular backup jobs.

9.2 Disconnected SMT Servers

In some restricted environments it is not possible for SMT servers to access the Internet because they are located on disconnected or isolated networks. In this case, you can back up the relevant data on an external storage device using special parameters with the SMT commands.

You need an external SMT server that mirrors the repositories from SUSE Customer Center. Then you can transfer these repositories to the SMT servers on the isolated network using the external storage device.

SMT Disconnected Setup
Figure 9.1: SMT Disconnected Setup

Although the initial setup of this solution requires additional configuration, the regular update synchronization with SUSE Customer Center and distribution to isolated servers is simple. The steps required during the initial setup are as follows:

  • Installing and configuring the external SMT server

  • Installing the internal server

  • Editing /etc/smt.conf and setting up a cron job on the internal SMT server

  • Transferring the SUSE Customer Center data from the external SMT server to the internal server

  • Enabling and disabling repositories on the internal server

  • Creating an SMT database replacement file on the internal server—when performing the mirror jobs, the file can be used instead of the normal Maria DB database

Day-to-day operation requires the following actions:

  • Running the smt-mirror job on the external server

  • Synchronizing the mirrored repositories from the external storage device to the internal SMT server

Below is a detailed description of the individual steps.

Procedure 9.1: External SMT Server Configuration for the Disconnected Setup
  1. Install and configure SMT as described in Chapter 1, SMT Installation.

  2. Enable the repositories for use by the internal SMT servers.

  3. Perform a standard repository mirroring from SUSE Customer Center with smt-mirror.

  4. Attach a removable storage device to the server and mount it.

  5. Export the required SUSE Customer Center data to a directory on the mounted storage device:

    1. Create a directory with correct permissions for storing the data. Because the smt commands run as the smt user (whose numeric UID can differ between the servers), you need to make permissions for the directories on the external storage device less restrictive:

      chmod o+w /path/to/scc/dir/on/storage/device
    2. Export the SUSE Customer Center data:

      smt-sync --todir /path/to/scc/dir/on/storage/device
  6. Create a directory with correct permissions:

    mkdir /path/to/repository/on/storage/device
    chmod o+w /path/to/repository/on/storage/device
  7. Unmount and detach the storage device.

Procedure 9.2: Internal SMT Server Configuration for the Disconnected Setup
  1. Ensure you have a working SUSE Linux Enterprise Server installation source.

  2. Install SMT the same way as on the external server with the following exceptions:

    1. Select Generate new SCC credentials in the SCC Credentials dialog.

    2. Ignore the error message when running the synchronization script in the Writing SMT Configuration phase of the wizard.

    3. Abort the SUSE Customer Center Configuration wizard and click OK in the list of installed add-on products.

  3. Re-launch the YaST Subscription Management Tool Server Configuration module (yast2 smt-server) and go to the Scheduled SMT Jobs tab.

  4. Delete SCC Registration and Synchronization of Updates jobs.

  5. Click OK to finish the wizard, provide the SMT user password, and acknowledge the synchronization error again.

  6. Prevent registration data upstream synchronization to SUSE Customer Center by setting

    forwardRegistration = false

    in /etc/smt.conf.

  7. Connect an external storage device and mount it.

  8. Populate the SMT database with the previously created SUSE Customer Center data:

    smt-sync --fromdir /path/to/scc/dir/on/mobile/disk
  9. Enable mirroring of the desired repositories using the smt-repos -e command.

  10. Create a database replacement file on the external storage device:

    smt-sync --createdbreplacementfile /path/to/dbrepl/file/on/mobile/disk
  11. Unmount and detach the storage device.

Now the configuration of both the external and internal SMT servers is complete. However, the update repository is still empty. After you run the following daily operation routines for the first time, the repository will be synchronized, and the internal SMT server will be ready to serve clients.

Procedure 9.3: Daily External SMT Server Operation
  1. Connect an external storage device and mount it.

  2. Perform a mirror to a directory on the storage device based on the file stored on it:

    smt-mirror --dbreplfile /path/to/dbrepl/file/on/storage/device \
     --fromlocalsmt --directory /path/to/repository/on/storage/device \
     -L /var/log/smt/smt-mirror-example.log
  3. Update the database on the storage device with the product and subscription info from SUSE Customer Center:

    smt-sync --todir /path/to/scc/dir/on/storage/device
  4. Optionally, scan the storage device for viruses and other unwanted content.

  5. Unmount and disconnect the storage device.

Procedure 9.4: Daily Internal SMT Server Operation
  1. Connect a storage device and mount it.

  2. Update the SUSE Customer Center data on the server:

    smt-sync --fromdir /path/to/scc/dir/on/storage/device
  3. Mirror from the storage device to the server:

    smt-mirror --fromdir /path/to/repository/on/storage/device
  4. Update the SUSE Customer Center data on the storage device with local changes in the mirror status since the last synchronization:

    smt-sync --createdbreplacementfile /path/to/dbrepl/file/on/storage/device
  5. Unmount and disconnect the storage device.

A SMT REST API

  • Filename: smt_appendix_api.xml
  • ID: smt.app.api

The SMT REST interface is meant for communication with SMT clients and integration into other Web services. The base URI for all the following REST calls is https://YOURSMTSERVER/=/1. The SMT server responds with XML data described for each call by an RNC snippet with comments.

Quick Reference
Note
Note: API for authenticating SMT clients.

Used internally in the smt-client package. Not intended for general administrative use!

GET /jobs                            get list of all jobs for client
GET /job/@next                       get the next job for client
GET /job/<jobid>                     get job with jobid for client.
                                     Note: this marks the job as retrieved
PUT /job/<jobid>                     update job having <jobid> using XML data.
                                     Note: updates only retrieved jobs

For backward compatibility reasons, the following are also available:

GET /jobs/@next                      same as GET /job/@next
GET /jobs/<jobid>                    same as GET /job/<jobid>
PUT /jobs/<jobid>                    same as PUT /job/<jobid>

API for general access (this needs authentication using credentials from the [REST] section of smt.conf).

GET /client                          get data of all clients
GET /client/<GUID>                   get data of client with specified GUID
GET /client/<GUID>/jobs              get client's job data
GET /client/<GUID>/patchstatus       get client's patch status
GET /client/<GUID>/job/@next         get client's next job
GET /client/<GUID>/job/<jobid>       get specified client job data
GET /client/@all/jobs                get job data of all clients
GET /client/@all/patchstatus         get patch status of all clients
GET /repo                            get all repositories known to SMT
GET /repo/<repoid>                   get details of repository with <repoid>
GET /repo/<repoid>/patches           get repository's patches
GET /patch/<patchid>                 get patch <patchid> details
GET /product                         get list of all products known to SMT
GET /product/<productid>             get details of product with <productid>
GET /product/<productid>/repos       get list of product's repositories

For backward compatibility reasons, plural forms are also available; for example:

GET /clients                         same as GET /client
GET /repos                           same as GET /repo
GET /product                         same as GET /product
Detailed Description

API for authenticating clients:

GET /jobs

Get list of all jobs for an authenticating client. When getting the jobs via this path they will not be set to the status retrieved.

Example:

<jobs>
  <job name="Patchstatus Job" created="2010-06-18 16:34:38" description="Patchstatus Job for Client 456" exitcode="" expires="" finished="" guid="456" guid_id="30" id="31" message="" parent_id="" persistent="1" retrieved="" status="0" stderr="" stdout="" targeted="" timelag="23:00:00" type="1" verbose="0">
    <arguments></arguments>
  </job>
  <job name="Software Push" created="2010-06-18 16:37:59" description="Software Push: mmv, whois" exitcode="" expires="" finished="" guid="456" guid_id="30" id="32" message="" parent_id="" persistent="0" retrieved="" status="0" stderr="" stdout="" targeted="" timelag="" type="2" verbose="0">
    <arguments>
      <packages>
        <package>mmv</package>
        <package>whois</package>
      </packages>
    </arguments>
  </job>
  <job name="Update Job" created="2010-06-18 16:38:39" description="Update Job" exitcode="" expires="" finished="" guid="456" guid_id="30" id="34" message="" parent_id="" persistent="0" retrieved="" status="0" stderr="" stdout="" targeted="" timelag="" type="3" verbose="0">
    <arguments></arguments>
  </job>
  <job name="Execute" created="2010-06-18 17:40:10" description="Execute custom command" exitcode="0" expires="" finished="2010-06-18 17:40:14" guid="456" guid_id="30" id="41" message="execute successfully finished" parent_id="" persistent="0" retrieved="2010-06-18 17:40:14" status="1" stderr="man:x:13:62:Manual pages viewer:/var/cache/man:/bin/bash" stdout="" targeted="" timelag="" type="4" verbose="1">
   <arguments command="grep man /etc/passwd" />
  </job>
  <job name="Reboot" created="2010-06-18 16:40:28" description="Reboot now" exitcode="" expires="2011-06-12 15:15:15" finished="" guid="456" guid_id="30" id="37" message="" parent_id="" persistent="0" retrieved="" status="0" stderr="" stdout="" targeted="2010-06-12 15:15:15" timelag="" type="5" verbose="0">
    <arguments></arguments>
  </job>
  <job name="Wait 5 sec. for exit 0." created="2010-06-18 16:40:59" description="Wait for 5 seconds and return with value 0." exitcode="" expires="" finished="" guid="456" guid_id="30" id="38" message="" parent_id="" persistent="0" retrieved="" status="0" stderr="" stdout="" targeted="" timelag="" type="7" verbose="0">
    <arguments exitcode="0" waittime="5" />
  </job>
  <job name="Eject job" created="2010-06-18 16:42:00" description="Job to eject the CD/DVD drawer" exitcode="" expires="" finished="" guid="456" guid_id="30" id="39" message="" parent_id="" persistent="0" retrieved="" status="0" stderr="" stdout="" targeted="" timelag="" type="8" verbose="0">
    <arguments action="toggle" />
  </job>
</jobs>
GET /jobs/@next

Get the next job for an authenticating client. The job will not be set to the retrieved status.

Example:

<job id="31" guid="456" type="patchstatus" verbose="false">
  <arguments></arguments>
</job>
GET /jobs/<jobid>

Get a job with the specified jobid for an authenticating client. The job will be set to the retrieved status.

When the client retrieves a job, not all the metadata is part of the XML response. However, it can be the full set of metadata, as smt-client only picks the data that is relevant. But a job retrieval should only contain the minimal set of data that is required to fulfill it.

RNC:

start = element job {
  attribute id {xsd:integer},         # the job ID. A job id alone is not unique.
                                      # A job is only uniquely identified with
                                      # guid and id. The same jobs for multiple
                                      # clients have the same job id.
  attribute parent_id {xsd:integer}?, # ID of the job on which this job depends
  attribute guid {xsd:string},
  attribute guid_id {xsd:integer}?,   # internal database ID of the client
                                      # (for compatibility reasons, if third
                                      # party application talks to SMT REST
                                      # service).
  attribute type {                    # job type ID string. Must be unique and
                                      # equal to the name of the Perl module on
                                      # the client.
    "softwarepush",
    "patchstatus",
    "<custom>"                        # add your own job types
  },
  attribute name {xsd:string},        # short custom name of the job, user-defined
  attribute description {xsd:string}, # custom description of what the job does
  attribute created {xsd:string},     # time stamp of creation
  attribute expires {xsd:string},     # expiration time stamp; the job expires
                                      # if not retrieved by then
  attribute finished {xsd:string},    # time stamp of job completion
  attribute retrieved {xsd:string},   # time stamp of retrieval of the job
  attribute persistent {xsd:boolean}?, # defines whether the job is a persistent
                                      # (repetitive) job
  attribute verbose {xsd:boolean},    # if true, output of job commands is
                                      # attached to the result
  attribute exitcode {xsd:integer},   # the last exit code of the system command
                                      # executed to complete the job
  attribute message {xsd:string},     # custom human-readable message the client
                                      # sends back as a result
  attribute status {                  # logical status of the job
    0,     # not yet worked on: The job may be already retrieved but no
           # result was sent back yet.
    1,     # success: The job was retrieved, processed and the client sent
           # back a success response.
    2,     # failed: The job was retrieved, processed and the client sent
           # back a failure response.
    3},    # denied by client: The job was retrieved but could not be
           # processed as the client denied to process this job type
           # (a client needs to allow all job types that should be processed,
           # any other will be denied).
  attribute stderr {text},            # standard error output of jobs's system
                                      # commands (filled if verbose)
  attribute stdout {text},            # standard output of jobs's system
                                      # commands (filled if verbose)
  attribute targeted {xsd:string},    # time stamp when this job will be
                                      # delivered at the earliest
  attribute timelag {xsd:string}?,    # interval time of a persistent job in
                                      # the format "HH:MM:SS" (HH can be
                                      # bigger than 23)
  element-arguments                   # job-type-specific XML data
}

Example (minimal job definition for a 'softwarepush' job):

<job id="32" guid="456" type="softwarepush" verbose="false">
  <arguments>
    <packages>
      <package>mmv</package>
      <package>whois</package>
    </packages>
  </arguments>
</job>
PUT /job/<jobid>

Update a job for an authenticating client using XML data.

A client can only send job results for jobs properly retrieved previously. The jobs will be set to status done (except for persistent jobs, in which case a new target time will be computed).

Examples:

  • Example for a successful patchstatus job:

    <job id="31" guid="abc123" exitcode="0" message="0:0:0:0 # PackageManager=0 Security=0 Recommended=0 Optional=0" status="1" stderr="" stdout="" />
  • Example for a failed softwarepush:

    <job id="32" guid="abc123" exitcode="104" message="softwarepush failed" status="2" stderr="" stdout="" />
  • Example for a successful update:

    <job id="34" guid="abc123" exitcode="0" message="update successfully finished" status="1" stderr="" stdout="" />
  • Example for a successful reboot job:

    <job id="37" guid="abc123" exitcode="0" message="reboot triggered" status="1" stderr="" stdout="" />
  • Execute for a successful wait job:

    <job id="38" guid="abc123" exitcode="0" message="wait successfully finished" status="1" stderr="" stdout="" />
  • Example for a successful eject job:

    <job id="39" guid="abc123" exitcode="0" message="eject successfully finished" status="1" stderr="" stdout="" />
  • Example for a successful execute job:

    <job id="41" guid="abc123" exitcode="0" message="execute successfully finished" status="1" stderr="man:x:13:62:Manual pages viewer:/var/cache/man:/bin/bash" stdout="" />

API for general access:

GET /repo/<repoid>

Returns detailed information about the specified repository. The <repoid> can be obtained using the /repos or /products/<productid>/repos/ call.

RNC:

start = element repo {                     # repository
  attribute id {xsd:integer},              # SMT ID of the repository
  attribute name {xsd:string},             # repository's Unix name
  attribute target {xsd:string},           # repository's target product
  attribute type {"nu" | "yum" | "zypp" | "pum"}, # type of repository
  element description {xsd:string},        # description of the repository
  element localpath {xsd:string},          # path to local SMT mirror of the
                                           # repository
  element url {xsd:anyURI},                # original URL of the repository
  element mirrored {
    attribute date {xsd:integer}           # timestamp of the last successful
                                           # mirror (empty if not mirrored yet)
  }
}

Example:

<repo name="SLES10-SP2-Updates" id="226" target="sles-10-i586" type="nu">
  <description>SLES10-SP2-Updates for sles-10-i586</description>
  <localpath>/local/htdocs/repo/$RCE/SLES10-SP2-Updates/sles-10-i586</localpath>
  <mirrored date="1283523440"/>
  <url>https://nu.novell.com/repo/$RCE/SLES10-SP2-Updates/sles-10-i586/</url>
</repo>
GET /repo/<repoid>/patches

Returns a list of all patches in the specified software repository. The repoid can be obtained using the /repos or /products/<productid>/repos/ call.

RNC:

start = element patches {
  element patch {
    attribute id {xsd:integer},                # SMT ID of the patch
    attribute name {xsd:string},               # patch's Unix name
    attribute version {xsd:integer}            # patch's version number
    attribute category {                       # patch importance category
      "security",
      "recommended",
      "optional",
      "mandatory"}
  }*
}

Example:

<patches>
  <patch name="slesp2-krb5" category="security" id="1471" version="6775"/>
  <patch name="slesp2-heartbeat" category="recommended" id="1524" version="5857"/>
  <patch name="slesp2-curl" category="security" id="1409" version="6402"/>
  ...
</patches>
GET /repos

Returns a list of all software repositories known to SMT. Those which are currently mirrored on SMT have non-empty mirror time stamp in the mirrored attribute.

RNC:

start = element repos {
  element repo {
    attribute id {xsd:integer},        # SMT ID of the repository
    attribute name {xsd:string},       # repository's Unix name
    attribute target {xsd:string},     # repository's target product
    attribute mirrored {xsd:integer}   # time stamp of the last successful mirror
                                       # (empty if not mirrored yet)
  }*
}

Example:

<repos>
  <repo name="SLE10-SDK-Updates" id="1" mirrored="" target="sles-10-x86_64"/>
  <repo name="SLE10-SDK-SP3-Pool" id="2" mirrored="" target="sles-10-ppc"/>
  <repo name="SLES10-SP2-Updates" id="226" mirrored="1283523440" target="sles-10-i586"/>
  ...
</repo>
GET /patch/<patchid>

Returns detailed information about the specified patch. The patchid can be obtained via the /repo/<repoid>/patches call.

RNC:

start = element patch {
  attribute id {xsd:integer},            # SMT ID of the patch
  attribute name {xsd:string},           # patch's Unix name
  attribute version {xsd:integer},       # patch's version number
  attribute category {                   # patch importance category
    "security",
    "recommended",
    "optional",
    "mandatory"},
  element title {xsd:string},            # title of the patch
  element description {text},            # description of issues fixed by the patch
  element issued {
    attribute date {xsd:integer}         # patch release time stamp
  },
  element packages {                     # packages which need update as part
                                         # of this patch
    element package {                    # individual RPM package data
      attribute name {xsd:string},       # package name
      attribute epoch {xsd:integer},     # epoch number
      attribute version {xsd:string},    # version string
      attribute release {xsd:string},    # release string
      attribute arch {xsd:string},       # architecture string
      element origlocation {xsd:anyURI}, # URL of the RPM package in the
                                         # original repository
      element smtlocation {xsd:anyURI}   # URL of the RPM package at the SMT server
    }*
  },
  element references {                   # references to issues fixed by this
                                         # patch
    element reference {                  # individual reference details
      attribute id,                      # ID number of the issue (bugzilla
                                         # or CVE number)
      attribute title {xsd:string},      # issue title
      attribute type {"bugzilla","cve"}, # type of the issue
      attribute href {xsd:anyURI}        # URL of the issue in its issue
                                         # tracking system
    }*
  }
}

Example:

<patch name="slesp2-krb5" category="security" id="1471" version="6775">
  <description>
    Specially crafted AES and RC4 packets could allow unauthenticated
    remote attackers to trigger an integer overflow leads to heap memory
    corruption (CVE-2009-4212). This has been fixed.
    Specially crafted AES and RC4 packets could allow
    unauthenticated remote attackers to trigger an integer
    overflow leads to heap memory corruption (CVE-2009-4212).
  </description>
  <issued date="1263343020"/>
  <packages>
    <package name="krb5" arch="i586" epoch="" release="19.43.2" version="1.4.3">
      <origlocation>https://nu.novell.com/repo/$RCE/SLES10-SP2-Updates/sles-10-i586/rpm/i586/krb5-1.4.3-19.43.2.i586.rpm</origlocation>
      <smtlocation>http://kompost.suse.cz/repo/$RCE/SLES10-SP2-Updates/sles-10-i586/rpm/i586/krb5-1.4.3-19.43.2.i586.rpm</smtlocation>
    </package>
    <package name="krb5-apps-servers" arch="i586" epoch="" release="19.43.2" version="1.4.3">
      <origlocation>https://nu.novell.com/repo/$RCE/SLES10-SP2-Updates/sles-10-i586/rpm/i586/krb5-apps-servers-1.4.3-19.43.2.i586.rpm</origlocation>
      <smtlocation>http://kompost.suse.cz/repo/$RCE/SLES10-SP2-Updates/sles-10-i586/rpm/i586/krb5-apps-servers-1.4.3-19.43.2.i586.rpm</smtlocation>
    </package>
    ...
  </packages>
  <references>
    <reference id="535943" href="https://bugzilla.suse.com/show_bug.cgi?id=535943" title="bug number 535943" type="bugzilla"/>
    <reference id="CVE-2009-4212" href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-4212" title="CVE-2009-4212" type="cve"/>
  </references>
  <title>Security update for Kerberos 5</title>
</patch>
GET /products

Returns list of all products known to SMT.

RNC:

start element products {
  element product {
    attribute id {xsd:integer},      # SMT ID of the product
    attribute name {xsd:string},     # Unix name of the product
    attribute version {xsd:string},  # version string
    attribute rel {xsd:string},      # release string
    attribute arch {xsd:string},     # target machine architecture string
    attribute uiname {xsd:string}    # name of the product to be
                                     # displayed to users
  }*
}

Example:

<products>
  <product name="SUSE_SLED" arch="x86_64" id="1824" rel="" uiname="SUSE Linux Enterprise Desktop 11 SP1" version="11.1"/>
  <product name="SUSE_SLES" arch="i686" id="1825" rel="" uiname="SUSE Linux Enterprise Server 11 SP1" version="11.1"/>
  <product name="sle-hae" arch="i686" id="1880" rel="" uiname="SUSE Linux Enterprise High Availability Extension 11 SP1" version="11.1"/>
  <product name="SUSE-Linux-Enterprise-Thin-Client" arch="" id="940" rel="SP1" uiname="SUSE Linux Enterprise 10 Thin Client SP1" version="10"/>
  ...
</products>
GET /product/<productid>

Returns information about the specified product. The productid can be obtained from data returned by the /products call.

RNC:

start = element product {
  attribute id {xsd:integer},       # SMT ID of the product
  attribute name {xsd:string},      # Unix name of the product
  attribute version {xsd:string},   # version string
  attribute rel {xsd:string},       # release string
  attribute arch {xsd:string},      # target machine architecture string
  attribute uiname {xsd:string}     # name of the product to be displayed
                                    # to users
}

Example:

<product name="SUSE_SLED" arch="x86_64" id="1824" rel="" uiname="SUSE Linux Enterprise Server 11 SP1" version="11.1"/>
GET /product/<productid>/repos

Returns the list of all software repositories for the specified product. The productid can be obtained from the data returned by the /products call.

RNC:

See the /repos call.

Example:

<repos>
  <repo name="SLED11-SP1-Updates" id="143" mirrored="" target="sle-11-x86_64"/>
  <repo name="SLE11-SP1-Debuginfo-Pool" id="400" mirrored="" target="sle-11-x86_64"/>
  <repo name="SLED11-Extras" id="417" mirrored="" target="sle-11-x86_64"/>
  <repo name="SLED11-SP1-Pool" id="215" mirrored="" target="sle-11-x86_64"/>
  <repo name="nVidia-Driver-SLE11-SP1" id="469" mirrored="" target=""/>
  <repo name="ATI-Driver-SLE11-SP1" id="411" mirrored="" target=""/>
  <repo name="SLE11-SP1-Debuginfo-Updates" id="6" mirrored="" target="sle-11-x86_64"/>
</repos>

B Documentation Updates

  • Filename: smt_docupdates.xml
  • ID: app.smt.docupdates

This chapter lists content changes for this document.

This manual was updated on the following dates:

B.1 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)

General

B.2 April 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP2)

Bugfixes

B.3 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)

General
  • The e-mail address for documentation feedback has changed to doc-team@suse.com.

  • The documentation for Docker has been enhanced and renamed to Docker Guide.

General Updates to this Guide
About This Guide
  • Replaced the introductory text with a more descriptive one, plus added a schema.

Chapter 1, SMT Installation
Chapter 3, Mirroring Repositories on the SMT Server
Chapter 4, Managing Repositories with YaST SMT Server Management
Chapter 5, Managing Client Machines with SMT
Chapter 7, SMT Tools and Configuration Files
Bugfixes

B.4 March 2016 (Maintenance Release of SUSE Linux Enterprise Server 12 SP1)

Chapter 1, SMT Installation

Fixed typos: my.conf.rpmnew to my.cnf.rpmnew and my.conf to my.cnf (https://bugzilla.suse.com/show_bug.cgi?id=964121).

B.5 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)

General
  • SMT Guide is now part of the documentation for SUSE Linux Enterprise Server.

  • Add-ons provided by SUSE have been renamed as modules and extensions. The manuals have been updated to reflect this change.

  • Numerous small fixes and additions to the documentation, based on technical feedback.

  • The registration service has been changed from Novell Customer Center to SUSE Customer Center.

  • In YaST, you will now reach Network Settings via the System group. Network Devices is gone (https://bugzilla.suse.com/show_bug.cgi?id=867809).

Chapter 1, SMT Installation
Chapter 3, Mirroring Repositories on the SMT Server
Chapter 7, SMT Tools and Configuration Files
Chapter 8, Configuring Clients to Use SMT
Bugfixes
SUSE Linux Enterprise Server 12 SP3

Storage Administration Guide

Provides information about how to manage storage devices on a SUSE Linux Enterprise Server.

Publication Date: April 04, 2018
About This Guide
Available Documentation
Feedback
Documentation Conventions
I File Systems and Mounting
1 Overview of File Systems in Linux
1.1 Terminology
1.2 Btrfs
1.3 XFS
1.4 Ext2
1.5 Ext3
1.6 Ext4
1.7 ReiserFS
1.8 Other Supported File Systems
1.9 Large File Support in Linux
1.10 Linux Kernel Storage Limitations
1.11 Troubleshooting File Systems
1.12 Additional Information
2 Resizing File Systems
2.1 Use Cases
2.2 Guidelines for Resizing
2.3 Changing the Size of a Btrfs File System
2.4 Changing the Size of an XFS File System
2.5 Changing the Size of an Ext2, Ext3, or Ext4 File System
2.6 Changing the Size of a Reiser File System
3 Using UUIDs to Mount Devices
3.1 Persistent Device Names with udev
3.2 Understanding UUIDs
3.3 Additional Information
4 Multi-tier Caching for Block Device Operations
4.1 General Terminology
4.2 Caching Modes
4.3 bcache
4.4 lvmcache
II Logical Volumes (LVM)
5 LVM Configuration
5.1 Understanding the Logical Volume Manager
5.2 Creating Volume Groups
5.3 Creating Logical Volumes
5.4 Automatically Activating Non-Root LVM Volume Groups
5.5 Resizing an Existing Volume Group
5.6 Resizing a Logical Volume
5.7 Deleting a Volume Group or a Logical Volume
5.8 Using LVM Commands
5.9 Tagging LVM2 Storage Objects
6 LVM Volume Snapshots
6.1 Understanding Volume Snapshots
6.2 Creating Linux Snapshots with LVM
6.3 Monitoring a Snapshot
6.4 Deleting Linux Snapshots
6.5 Using Snapshots for Virtual Machines on a Virtual Host
6.6 Merging a Snapshot with the Source Logical Volume to Revert Changes or Roll Back to a Previous State
III Software RAID
7 Software RAID Configuration
7.1 Understanding RAID Levels
7.2 Soft RAID Configuration with YaST
7.3 Troubleshooting Software RAIDs
7.4 For More Information
8 Configuring Software RAID for the Root Partition
8.1 Prerequisites for Using a Software RAID Device for the Root Partition
8.2 Setting Up the System with a Software RAID Device for the Root (/) Partition
9 Creating Software RAID 10 Devices
9.1 Creating Nested RAID 10 Devices with mdadm
9.2 Creating a Complex RAID 10
10 Creating a Degraded RAID Array
11 Resizing Software RAID Arrays with mdadm
11.1 Increasing the Size of a Software RAID
11.2 Decreasing the Size of a Software RAID
12 Storage Enclosure LED Utilities for MD Software RAIDs
12.1 The Storage Enclosure LED Monitor Service
12.2 The Storage Enclosure LED Control Application
12.3 Additional Information
IV Network Storage
13 iSNS for Linux
13.1 How iSNS Works
13.2 Installing iSNS Server for Linux
13.3 Configuring iSNS Discovery Domains
13.4 Starting the iSNS Service
13.5 For More Information
14 Mass Storage over IP Networks: iSCSI
14.1 Installing the iSCSI LIO Target Server and iSCSI Initiator
14.2 Setting Up an iSCSI LIO Target Server
14.3 Configuring iSCSI Initiator
14.4 Using iSCSI Disks when Installing
14.5 Troubleshooting iSCSI
14.6 iSCSI LIO Target Terminology
14.7 Additional Information
15 Fibre Channel Storage over Ethernet Networks: FCoE
15.1 Configuring FCoE Interfaces during the Installation
15.2 Installing FCoE and the YaST FCoE Client
15.3 Managing FCoE Services with YaST
15.4 Configuring FCoE with Commands
15.5 Managing FCoE Instances with the FCoE Administration Tool
15.6 Additional Information
16 NVMe over Fabric
16.1 Overview
16.2 Setting Up an NVMe over Fabric Host
16.3 Setting Up an NVMe over Fabric Target
16.4 Special Hardware Configuration
16.5 More Information
17 Managing Multipath I/O for Devices
17.1 Understanding Multipath I/O
17.2 Hardware Support
17.3 Planning for Multipathing
17.4 Multipath Management Tools
17.5 Configuring the System for Multipathing
17.6 Creating or Modifying the /etc/multipath.conf File
17.7 Configuring Default Policies for Polling, Queuing, and Failback
17.8 Blacklisting Non-Multipath Devices
17.9 Configuring User-Friendly Names or Alias Names
17.10 Configuring Path Failover Policies and Priorities
17.11 Configuring Multipath I/O for the Root Device
17.12 Configuring Multipath I/O for an Existing Software RAID
17.13 Using LVM2 on Multipath Devices
17.14 Best Practice
17.15 Troubleshooting MPIO
18 Managing Access Control Lists over NFSv4
A Documentation Updates
A.1 March 2018
A.2 December 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)
A.3 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)
A.4 April 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP2)
A.5 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)
A.6 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)
A.7 February 2015 (Documentation Maintenance Update)
A.8 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)
B GNU Licenses
B.1 GNU Free Documentation License

Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

About This Guide

  • Filename: storage_intro.xml
  • ID: storage.preface

This guide provides information about how to manage storage devices on SUSE Linux Enterprise Server 12 SP3. For information about partitioning and managing devices, see Chapter 12, Advanced Disk Setup. This guide is intended for system administrators.

1 Available Documentation

  • Filename: common_intro_available_doc_i.xml
  • ID: no ID found
Note
Note: Online Documentation and Latest Updates

Documentation for our products is available at http://www.suse.com/documentation/, where you can also find the latest updates, and browse or download the documentation in various formats.

In addition, the product documentation is usually available in your installed system under /usr/share/doc/manual.

The following documentation is available for this product:

Installation Quick Start

Lists the system requirements and guides you step-by-step through the installation of SUSE Linux Enterprise Server from DVD, or from an ISO image.

Deployment Guide

Shows how to install single or multiple systems and how to exploit the product inherent capabilities for a deployment infrastructure. Choose from various approaches, ranging from a local installation or a network installation server to a mass deployment using a remote-controlled, highly-customized, and automated installation technique.

Administration Guide

Covers system administration tasks like maintaining, monitoring and customizing an initially installed system.

Virtualization Guide

Describes virtualization technology in general, and introduces libvirt—the unified interface to virtualization—and detailed information on specific hypervisors.

Storage Administration Guide

Provides information about how to manage storage devices on a SUSE Linux Enterprise Server.

AutoYaST

AutoYaST is a system for unattended mass deployment SUSE Linux Enterprise Server systems using an AutoYaST profile containing installation and configuration data. The manual guides you through the basic steps of auto-installation: preparation, installation, and configuration.

Security Guide

Introduces basic concepts of system security, covering both local and network security aspects. Shows how to use the product inherent security software like AppArmor or the auditing system that reliably collects information about any security-relevant events.

Security and Hardening Guide

Deals with the particulars of installing and setting up a secure SUSE Linux Enterprise Server, and additional post-installation processes required to further secure and harden that installation. Supports the administrator with security-related choices and decisions.

System Analysis and Tuning Guide

An administrator's guide for problem detection, resolution and optimization. Find how to inspect and optimize your system by means of monitoring tools and how to efficiently manage resources. Also contains an overview of common problems and solutions and of additional help and documentation resources.

SMT Guide

An administrator's guide to Subscription Management Tool—a proxy system for SUSE Customer Center with repository and registration targets. Learn how to install and configure a local SMT server, mirror and manage repositories, manage client machines, and configure clients to use SMT.

GNOME User Guide

Introduces the GNOME desktop of SUSE Linux Enterprise Server. It guides you through using and configuring the desktop and helps you perform key tasks. It is intended mainly for end users who want to make efficient use of GNOME as their default desktop.

2 Feedback

  • Filename: common_intro_feedback_i.xml
  • ID: no ID found

Several feedback channels are available:

Bugs and Enhancement Requests

For services and support options available for your product, refer to http://www.suse.com/support/.

Help for openSUSE is provided by the community. Refer to https://en.opensuse.org/Portal:Support for more information.

To report bugs for a product component, go to https://scc.suse.com/support/requests, log in, and click Create New.

User Comments

We want to hear your comments about and suggestions for this manual and the other documentation included with this product. Use the User Comments feature at the bottom of each page in the online documentation or go to http://www.suse.com/documentation/feedback.html and enter your comments there.

Mail

For feedback on the documentation of this product, you can also send a mail to doc-team@suse.com. Make sure to include the document title, the product version and the publication date of the documentation. To report errors or suggest enhancements, provide a concise description of the problem and refer to the respective section number and page (or URL).

3 Documentation Conventions

  • Filename: common_intro_typografie_i.xml
  • ID: no ID found

The following notices and typographical conventions are used in this documentation:

  • /etc/passwd: directory names and file names

  • PLACEHOLDER: replace PLACEHOLDER with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • package name : name of a package

  • Alt, AltF1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File › Save As: menu items, buttons

  • x86_64 This paragraph is only relevant for the AMD64/Intel 64 architecture. The arrows mark the beginning and the end of the text block.

    System z, POWER This paragraph is only relevant for the architectures z Systems and POWER. The arrows mark the beginning and the end of the text block.

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

  • Commands that must be run with root privileges. Often you can also prefix these commands with the sudo command to run them as non-privileged user.

    root # command
    tux > sudo command
  • Commands that can be run by non-privileged users.

    tux > command
  • Notices

    Warning
    Warning: Warning Notice

    Vital information you must be aware of before proceeding. Warns you about security issues, potential loss of data, damage to hardware, or physical hazards.

    Important
    Important: Important Notice

    Important information you should be aware of before proceeding.

    Note
    Note: Note Notice

    Additional information, for example about differences in software versions.

    Tip
    Tip: Tip Notice

    Helpful information, like a guideline or a piece of practical advice.

Part I File Systems and Mounting

1 Overview of File Systems in Linux

SUSE Linux Enterprise Server ships with different file systems from which to choose, including Btrfs, Ext4, Ext3, Ext2, ReiserFS and XFS. Each file system has its own advantages and disadvantages. For a side-by-side feature comparison of the major operating systems in SUSE Linux Enterprise Server, see http://www.suse.com/products/server/technical-information/#FileSystem (File System Support and Sizes). This chapter contains an overview of how these file systems work and what advantages they offer.

2 Resizing File Systems

Resizing file systems—not to be confused with resizing partitions or volumes—can be used to make space available on physical volumes or to use additional space available on a physical volume.

3 Using UUIDs to Mount Devices

This section describes the use of UUIDs (Universally Unique Identifiers) instead of device names (such as /dev/sda1) to identify file system devices. Starting with SUSE Linux Enterprise Server 12, UUIDs are used by default in the boot loader file and the /etc/fstab file.

4 Multi-tier Caching for Block Device Operations

A multi-tier cache is a replicated/distributed cache that consists of at least two tiers: one is represented by slower but cheaper rotational block devices (hard disks), while the other is more expensive but performs faster data operations (for example SSD flash disks).

1 Overview of File Systems in Linux

  • Filename: storage_filesystems.xml
  • ID: cha.filesystems
Abstract

SUSE Linux Enterprise Server ships with different file systems from which to choose, including Btrfs, Ext4, Ext3, Ext2, ReiserFS and XFS. Each file system has its own advantages and disadvantages. For a side-by-side feature comparison of the major operating systems in SUSE Linux Enterprise Server, see http://www.suse.com/products/server/technical-information/#FileSystem (File System Support and Sizes). This chapter contains an overview of how these file systems work and what advantages they offer.

With SUSE Linux Enterprise 12, Btrfs is the default file system for the operating system and XFS is the default for all other use cases. SUSE also continues to support the Ext family of file systems, ReiserFS and OCFS2. By default, the Btrfs file system will be set up with subvolumes. Snapshots will be automatically enabled for the root file system using the snapper infrastructure. For more information about snapper, refer to Chapter 7, System Recovery and Snapshot Management with Snapper.

Professional high-performance setups might require a highly available storage system. To meet the requirements of high-performance clustering scenarios, SUSE Linux Enterprise Server includes OCFS2 (Oracle Cluster File System 2) and the Distributed Replicated Block Device (DRBD) in the High Availability Extension add-on. These advanced storage systems are not covered in this guide. For information, see the SUSE Linux Enterprise High Availability Extension Administration Guide at http://www.suse.com/doc.

It is very important to remember that no file system best suits all kinds of applications. Each file system has its particular strengths and weaknesses, which must be taken into account. In addition, even the most sophisticated file system cannot replace a reasonable backup strategy.

The terms data integrity and data consistency, when used in this section, do not refer to the consistency of the user space data (the data your application writes to its files). Whether this data is consistent must be controlled by the application itself.

Unless stated otherwise in this section, all the steps required to set up or change partitions and file systems can be performed by using the YaST Partitioner (which is also strongly recommended). For information, see Chapter 12, Advanced Disk Setup.

1.1 Terminology

metadata

A data structure that is internal to the file system. It ensures that all of the on-disk data is properly organized and accessible. Essentially, it is data about the data. Almost every file system has its own structure of metadata, which is one reason the file systems show different performance characteristics. It is extremely important to maintain metadata intact, because otherwise all data on the file system could become inaccessible.

inode

A data structure on a file system that contains a variety of information about a file, including size, number of links, pointers to the disk blocks where the file contents are actually stored, and date and time of creation, modification, and access.

journal

In the context of a file system, a journal is an on-disk structure containing a type of log in which the file system stores what it is about to change in the file system’s metadata. Journaling greatly reduces the recovery time of a file system because it has no need for the lengthy search process that checks the entire file system at system start-up. Instead, only the journal is replayed.

1.2 Btrfs

Btrfs is a copy-on-write (COW) file system developed by Chris Mason. It is based on COW-friendly B-trees developed by Ohad Rodeh. Btrfs is a logging-style file system. Instead of journaling the block changes, it writes them in a new location, then links the change in. Until the last write, the new changes are not committed.

1.2.1 Key Features

Btrfs provides fault tolerance, repair, and easy management features, such as the following:

  • Writable snapshots that allow you to easily roll back your system if needed after applying updates, or to back up files.

  • Subvolume support: Btrfs creates a default subvolume in its assigned pool of space. It allows you to create additional subvolumes that act as individual file systems within the same pool of space. The number of subvolumes is limited only by the space allocated to the pool.

  • The online check and repair functionality scrub is available as part of the Btrfs command line tools. It verifies the integrity of data and metadata, assuming the tree structure is fine. You can run scrub periodically on a mounted file system; it runs as a background process during normal operation.

  • Different RAID levels for metadata and user data.

  • Different checksums for metadata and user data to improve error detection.

  • Integration with Linux Logical Volume Manager (LVM) storage objects.

  • Integration with the YaST Partitioner and AutoYaST on SUSE Linux Enterprise Server. This also includes creating a Btrfs file system on Multiple Devices (MD) and Device Mapper (DM) storage configurations.

  • Offline migration from existing Ext2, Ext3, and Ext4 file systems.

  • Boot loader support for /boot, allowing to boot from a Btrfs partition.

  • Multivolume Btrfs is supported in RAID0, RAID1, and RAID10 profiles in SUSE Linux Enterprise Server 12 SP3. Higher RAID levels are not supported yet, but might be enabled with a future service pack.

  • Use Btrfs commands to set up transparent compression.

1.2.2 The Root File System Setup on SUSE Linux Enterprise Server

By default, SUSE Linux Enterprise Server is set up using Btrfs and snapshots for the root partition. Snapshots allow you to easily roll back your system if needed after applying updates, or to back up files. Snapshots can easily be managed with the SUSE Snapper infrastructure as explained in Chapter 7, System Recovery and Snapshot Management with Snapper. For general information about the SUSE Snapper project, see the Snapper Portal wiki at OpenSUSE.org (http://snapper.io).

When using a snapshot to roll back the system, it must be ensured that data such as user's home directories, Web and FTP server contents or log files do not get lost or overwritten during a roll back. This is achieved by using Btrfs subvolumes on the root file system. Subvolumes can be excluded from snapshots. The default root file system setup on SUSE Linux Enterprise Server as proposed by YaST during the installation contains the following subvolumes. They are excluded from snapshots for the reasons given below.

/boot/grub2/i386-pc, /boot/grub2/x86_64-efi, /boot/grub2/powerpc-ieee1275, /boot/grub2/s390x-emu

A rollback of the boot loader configuration is not supported. The directories listed above are architecture-specific. The first two directories are present on AMD64/Intel 64 machines, the latter two on IBM POWER and on IBM z Systems, respectively.

/home

If /home does not reside on a separate partition, it is excluded to avoid data loss on rollbacks.

/opt, /var/opt

Third-party products usually get installed to /opt. It is excluded to avoid uninstalling these applications on rollbacks.

/srv

Contains data for Web and FTP servers. It is excluded to avoid data loss on rollbacks.

/tmp, /var/tmp, /var/cache, /var/crash

All directories containing temporary files and caches are excluded from snapshots.

/usr/local

This directory is used when manually installing software. It is excluded to avoid uninstalling these installations on rollbacks.

/var/lib/libvirt/images

The default location for virtual machine images managed with libvirt. Excluded to ensure virtual machine images are not replaced with older versions during a rollback. By default, this subvolume is created with the option no copy on write.

/var/lib/mailman, /var/spool

Directories containing mails or mail queues are excluded to avoid a loss of mails after a rollback.

/var/lib/named

Contains zone data for the DNS server. Excluded from snapshots to ensure a name server can operate after a rollback.

/var/lib/mariadb, /var/lib/mysql, /var/lib/pgqsl

These directories contain database data. By default, these subvolumes are created with the option no copy on write.

/var/log

Log file location. Excluded from snapshots to allow log file analysis after the rollback of a broken system.

Warning
Warning: Support for Rollbacks

Rollbacks are only supported by the SUSE support if you do not remove any of the preconfigured subvolumes. You may, however, add additional subvolumes using the YaST Partitioner.

1.2.2.1 Mounting Compressed Btrfs File Systems

Note
Note: GRUB 2 and LZO Compressed Root

GRUB 2 cannot read an lzo compressed root. You need a separate /boot partition to use compression.

Since SLE12 SP1, compression for Btrfs file systems is supported. Use the compress or compress-force option and select the compression algorithm, lzo or zlib (the default). The zlib compression has a higher compression ratio while lzo is faster and takes less CPU load.

For example:

root # mount -o compress /dev/sdx /mnt

In case you create a file, write to it, and the compressed result is greater or equal to the uncompressed size, Btrfs will skip compression for future write operations forever for this file. If you do not like this behavior, use the compress-force option. This can be useful for files that have some initial uncompressible data.

Note, compression takes effect for new files only. Files that were written without compression are not compressed when the file system is mounted with the compress or compress-force option. Furthermore, files with the nodatacow attribute never get their extents compressed:

root # chattr +C FILE
root # mount -o nodatacow  /dev/sdx /mnt

In regard to encryption, this is independent from any compression. After you have written some data to this partition, print the details:

root # btrfs filesystem show /mnt
btrfs filesystem show /mnt
Label: 'Test-Btrfs'  uuid: 62f0c378-e93e-4aa1-9532-93c6b780749d
        Total devices 1 FS bytes used 3.22MiB
      devid    1 size 2.00GiB used 240.62MiB path /dev/sdb1

If you want this to be permanent, add the compress or compress-force option into the /etc/fstab configuration file. For example:

UUID=1a2b3c4d /home btrfs subvol=@/home,compress 0 0

1.2.2.2 Mounting Subvolumes

A system rollback from a snapshot on SUSE Linux Enterprise Server is performed by booting from the snapshot first. This allows you to check the snapshot while running before doing the rollback. Being able to boot from snapshots is achieved by mounting the subvolumes (which would normally not be necessary).

In addition to the subvolumes listed in Section 1.2.2, “The Root File System Setup on SUSE Linux Enterprise Server a volume named @ exists. This is the default subvolume that will be mounted as the root partition (/). The other subvolumes will be mounted into this volume.

When booting from a snapshot, not the @ subvolume will be used, but rather the snapshot. The parts of the file system included in the snapshot will be mounted read-only as /. The other subvolumes will be mounted writable into the snapshot. This state is temporary by default: the previous configuration will be restored with the next reboot. To make it permanent, execute the snapper rollback command. This will make the snapshot that is currently booted the new default subvolume, which will be used after a reboot.

1.2.2.3 Checking for Free Space

File system usage is usually checked by running the df command. On a Btrfs file system, the output of df can be misleading, because in addition to the space the raw data allocates, a Btrfs file system also allocates and uses space for metadata.

Consequently a Btrfs file system may report being out of space even though it seems that plenty of space is still available. In that case, all space allocated for the metadata is used up. Use the following commands to check for used and available space on a Btrfs file system:

btrfs filesystem show
tux > sudo btrfs filesystem show /
Label: 'ROOT'  uuid: 52011c5e-5711-42d8-8c50-718a005ec4b3
        Total devices 1 FS bytes used 10.02GiB
        devid    1 size 20.02GiB used 13.78GiB path /dev/sda3

Shows the total size of the file system and its usage. If these two values in the last line match, all space on the file system has been allocated.

btrfs filesystem df
tux > sudo btrfs filesystem df /
Data, single: total=13.00GiB, used=9.61GiB
System, single: total=32.00MiB, used=16.00KiB
Metadata, single: total=768.00MiB, used=421.36MiB
GlobalReserve, single: total=144.00MiB, used=0.00B

Shows values for allocated (total) and used space of the file system. If the values for total and used for the metadata are almost equal, all space for metadata has been allocated.

btrfs filesystem usage
tux > sudo btrfs filesystem usage /
Overall:
    Device size:                  20.02GiB
    Device allocated:             13.78GiB
    Device unallocated:            6.24GiB
    Device missing:                  0.00B
    Used:                         10.02GiB
    Free (estimated):              9.63GiB      (min: 9.63GiB)
    Data ratio:                       1.00
    Metadata ratio:                   1.00
    Global reserve:              144.00MiB      (used: 0.00B)

             Data     Metadata  System
Id Path      single   single    single   Unallocated
-- --------- -------- --------- -------- -----------
 1 /dev/sda3 13.00GiB 768.00MiB 32.00MiB     6.24GiB
-- --------- -------- --------- -------- -----------
   Total     13.00GiB 768.00MiB 32.00MiB     6.24GiB
   Used       9.61GiB 421.36MiB 16.00KiB

Shows data similar to that of the two previous commands combined.

For more information refer to man 8 btrfs-filesystem and https://btrfs.wiki.kernel.org/index.php/FAQ.

1.2.3 Migration from Ext and ReiserFS File Systems to Btrfs

You can migrate data volumes from existing Ext (Ext2, Ext3, or Ext4) or ReiserFS to the Btrfs file system. The conversion process occurs offline and in place on the device. The file system needs at least 15% of available free space on the device.

To convert the file system to Btrfs, take the file system offline, then enter:

sudo btrfs-convert DEVICE

To roll back the migration to the original file system, take the file system offline, then enter:

sudo btrfs-convert -r DEVICE
Warning
Warning: Root File System Conversion not Supported

Converting the root file system to Btrfs is not supported. Either keep the existing file system or re-install the whole system from scratch.

Important
Important: Possible Loss of Data

When rolling back to the original file system, all data will be lost that you added after the conversion to Btrfs. That is, only the original data is converted back to the previous file system.

1.2.4 Btrfs Administration

Btrfs is integrated in the YaST Partitioner and AutoYaST. It is available during the installation to allow you to set up a solution for the root file system. You can use the YaST Partitioner after the installation to view and manage Btrfs volumes.

Btrfs administration tools are provided in the btrfsprogs package. For information about using Btrfs commands, see the man 8 btrfs, man 8 btrfsck, and man 8 mkfs.btrfs commands. For information about Btrfs features, see the Btrfs wiki at http://btrfs.wiki.kernel.org.

1.2.5 Btrfs Quota Support for Subvolumes

The Btrfs root file system subvolumes /var/log, /var/crash and /var/cache can use all of the available disk space during normal operation, and cause a system malfunction. To help avoid this situation, SUSE Linux Enterprise Server now offers Btrfs quota support for subvolumes. If you set up the root file system by using the respective YaST proposal, it is prepared accordingly: quota groups (qgroup) for all subvolumes are already set up. To set a quota for a subvolume in the root file system, proceed as follows:

  1. Enable quota support:

    sudo btrfs quota enable /
  2. Get a list of subvolumes:

    sudo btrfs subvolume list /

    Quotas can only be set for existing subvolumes.

  3. Set a quota for one of the subvolumes that was listed in the previous step. A subvolume can either be identified by path (for example /var/tmp) or by 0/SUBVOLUME ID (for example 0/272). The following example sets a quota of five GB for /var/tmp.

    sudo btrfs qgroup limit 5G /var/tmp

    The size can either be specified in bytes (5000000000), kilobytes (5000000K), megabytes (5000M), or gigabytes (5G). The resulting values in bytes slightly differ, since 1024 Bytes = 1 KiB, 1024 KiB = 1 MiB, etc.

  4. To list the existing quotas, use the following command. The column max_rfer shows the quota in bytes.

    sudo btrfs qgroup show -r /
Tip
Tip: Nullifying a Quota

In case you want to nullify an existing quota, set a quota size of none:

sudo btrfs qgroup limit none /var/tmp

To disable quota support for a partition and all its subvolumes, use btrfs quota disable:

sudo btrfs quota disable /

See the man 8 btrfs-qgroup and man 8 btrfs-quota for more details. The UseCases page on the Btrfs wiki (https://btrfs.wiki.kernel.org/index.php/UseCases) also provides more information.

1.2.6 Btrfs send/receive

Btrfs allows to make snapshots to capture the state of the file system. Snapper, for example, uses this feature to create snapshots before and after system changes, allowing a rollback. However, together with the send/receive feature, snapshots can also be used to create and maintain copies of a file system in a remote location. This feature can, for example, be used to do incremental backups.

A btrfs send operation calculates the difference between two read-only snapshots from the same subvolume and sends it to a file or to STDOUT. A Btrfs receive operation takes the result of the send command and applies it to a snapshot.

1.2.6.1 Prerequisites

To use Btrfs's send/receive feature, the following requirements need to be met:

  • A Btrfs file system is required on the source side (send) and on the target side (receive).

  • Btrfs send/receive operates on snapshots, therefore the respective data needs to reside in a Btrfs subvolume.

  • Snapshots on the source side need to be read-only.

  • SUSE Linux Enterprise 12 SP2 or better. Earlier versions of SUSE Linux Enterprise do not support send/receive.

1.2.6.2 Incremental Backups

The following procedure shows the basic usage of Btrfs send/receive using the example of creating incremental backups of /data (source side) in /backup/data (target side). /data needs to be a subvolume.

Procedure 1.1: Initial Setup
  1. Create the initial snapshot (called snapshot_0 in this example) on the source side and make sure it is written to the disk:

    sudo btrfs subvolume snapshot -r /data /data/bkp_data
    sync

    A new subvolume /data/bkp_data is created. It will be used as the basis for the next incremental backup and should be kept as a reference.

  2. Send the initial snapshot to the target side. Since this is the initial send/receive operation, the complete snapshot needs to be sent:

    sudo bash -c 'btrfs send /data/bkp_data | btrfs receive /backup'

    A new subvolume /backup/bkp_data is created on the target side.

When the initial setup has been finished, you can create incremental backups and send the differences between the current and previous snapshots to the target side. The procedure is always the same:

  1. Create a new snapshot on the source side.

  2. Send the differences to the target side.

  3. Optional: Rename and/or clean up snapshots on both sides.

Procedure 1.2: Performing an Incremental Backup
  1. Create a new snapshot on the source side and make sure it is written to the disk. In the following example the snapshot is named bkp_data_CURRENT_DATE:

    sudo btrfs subvolume snapshot -r /data /data/bkp_data_$(date +%F)
    sync

    A new subvolume, for example /data/bkp_data_2016-07-07, is created.

  2. Send the difference between the previous snapshot and the one you have created to the target side. This is achieved by specifying the previous snapshot with the option -p SNAPSHOT.

    sudo bash -c 'btrfs send -p /data/bkp_data /data/bkp_data_2016-07-07 \
    | btrfs receive /backup'

    A new subvolume /backup/bkp_data_2016-07-07 is created.

  3. As a result four snapshots, two on each side, exist:

    /data/bkp_data
    /data/bkp_data_2016-07-07
    /backup/bkp_data
    /backup/bkp_data_2016-07-07

    Now you have three options for how to proceed:

    • Keep all snapshots on both sides. With this option you can roll back to any snapshot on both sides while having all data duplicated at the same time. No further action is required. When doing the next incremental backup, keep in mind to use the next-to-last snapshot as parent for the send operation.

    • Only keep the last snapshot on the source side and all snapshots on the target side. Also allows to roll back to any snapshot on both sides—to do a rollback to a specific snapshot on the source side, perform a send/receive operation of a complete snapshot from the target side to the source side. Do a delete/move operation on the source side.

    • Only keep the last snapshot on both sides. This way you have a backup on the target side that represents the state of the last snapshot made on the source side. It is not possible to roll back to other snapshots. Do a delete/move operation on the source and the target side.

    1. To only keep the last snapshot on the source side, perform the following commands:

      sudo btrfs subvolume delete /data/bkp_data
      sudo mv /data/bkp_data_2016-07-07 /data/bkp_data

      The first command will delete the previous snapshot, the second command renames the current snapshot to /data/bkp_data. This ensures that the last snapshot that was backed up is always named /data/bkp_data. As a consequence, you can also always use this subvolume name as a parent for the incremental send operation.

    2. To only keep the last snapshot on the target side, perform the following commands:

      sudo btrfs subvolume delete /backup/bkp_data
      sudo mv /backup/bkp_data_2016-07-07 /backup/bkp_data

      The first command will delete the previous backup snapshot, the second command renames the current backup snapshot to /backup/bkp_data. This ensures that the latest backup snapshot is always named /backup/bkp_data.

Tip
Tip: Sending to a Remote Target Side

To send the snapshots to a remote machine, use SSH:

btrfs send /data/bkp_data | ssh root@jupiter.example.com 'btrfs receive /backup'

1.2.7 Data Deduplication Support

Btrfs supports data deduplication by replacing identical blocks in the file system with logical links to a single copy of the block in a common storage location. SUSE Linux Enterprise Server provides the tool duperemove for scanning the file system for identical blocks. When used on a Btrfs file system, it can also be used to deduplicate these blocks. duperemove is not installed by default. To make it available, install the package duperemove .

Note
Note: Use Cases

As of SUSE Linux Enterprise Server 12 SP3 duperemove is not suited to deduplicate the entire file system. It is intended to be used to deduplicate a set of 10 to 50 large files that possibly have lots of blocks in common, such as virtual machine images.

duperemove can either operate on a list of files or recursively scan a directory:

sudo duperemove OPTIONS file1 file2 file3
sudo duperemove -r OPTIONS directory

It operates in two modes: read-only and de-duping. When run in read-only mode (that is without the -d switch), it scans the given files or directories for duplicated blocks and prints them. This works on any file system.

Running duperemove in de-duping mode is only supported on Btrfs file systems. After having scanned the given files or directories, the duplicated blocks will be submitted for deduplication.

For more information see man 8 duperemove.

1.3 XFS

Originally intended as the file system for their IRIX OS, SGI started XFS development in the early 1990s. The idea behind XFS was to create a high-performance 64-bit journaling file system to meet extreme computing challenges. XFS is very good at manipulating large files and performs well on high-end hardware. XFS is the default file system for data partitions in SUSE Linux Enterprise Server.

A quick review of XFS’s key features explains why it might prove to be a strong competitor for other journaling file systems in high-end computing.

1.3.1 High Scalability by Using Allocation Groups

At the creation time of an XFS file system, the block device underlying the file system is divided into eight or more linear regions of equal size. Those are called allocation groups. Each allocation group manages its own inodes and free disk space. Practically, allocation groups can be seen as file systems in a file system. Because allocation groups are rather independent of each other, more than one of them can be addressed by the kernel simultaneously. This feature is the key to XFS’s great scalability. Naturally, the concept of independent allocation groups suits the needs of multiprocessor systems.

1.3.2 High Performance through Efficient Management of Disk Space

Free space and inodes are handled by B+ trees inside the allocation groups. The use of B+ trees greatly contributes to XFS’s performance and scalability. XFS uses delayed allocation, which handles allocation by breaking the process into two pieces. A pending transaction is stored in RAM and the appropriate amount of space is reserved. XFS still does not decide where exactly (in file system blocks) the data should be stored. This decision is delayed until the last possible moment. Some short-lived temporary data might never make its way to disk, because it is obsolete by the time XFS decides where actually to save it. In this way, XFS increases write performance and reduces file system fragmentation. Because delayed allocation results in less frequent write events than in other file systems, it is likely that data loss after a crash during a write is more severe.

1.3.3 Preallocation to Avoid File System Fragmentation

Before writing the data to the file system, XFS reserves (preallocates) the free space needed for a file. Thus, file system fragmentation is greatly reduced. Performance is increased because the contents of a file are not distributed all over the file system.

Note
Note: The new XFS On-disk Format

Starting with version 12, SUSE Linux Enterprise Server supports the new on-disk format (v5) of the XFS file system. XFS file systems created by YaST will use this new format. The main advantages of this format are automatic checksums of all XFS metadata, file type support, and support for a larger number of access control lists for a file.

Note that this format is not supported by SUSE Linux Enterprise kernels older than version 3.12, by xfsprogs older than version 3.2.0, and GRUB 2 versions released before SUSE Linux Enterprise 12. This will be problematic if the file system should also be used from systems not meeting these prerequisites.

If you require interoperability of the XFS file system with older SUSE systems or other Linux distributions, format the file system manually using the mkfs.xfs command. This will create an XFS file system in the old format (unless you use the -m crc=1 option).

1.4 Ext2

The origins of Ext2 go back to the early days of Linux history. Its predecessor, the Extended File System, was implemented in April 1992 and integrated in Linux 0.96c. The Extended File System underwent several modifications and, as Ext2, became the most popular Linux file system for years. With the creation of journaling file systems and their short recovery times, Ext2 became less important.

A brief summary of Ext2’s strengths might help understand why it was—and in some areas still is—the favorite Linux file system of many Linux users.

Solidity and Speed

Being an old-timer, Ext2 underwent many improvements and was heavily tested. This might be the reason people often refer to it as rock-solid. After a system outage when the file system could not be cleanly unmounted, e2fsck starts to analyze the file system data. Metadata is brought into a consistent state and pending files or data blocks are written to a designated directory (called lost+found). In contrast to journaling file systems, e2fsck analyzes the entire file system and not only the recently modified bits of metadata. This takes significantly longer than checking the log data of a journaling file system. Depending on file system size, this procedure can take half an hour or more. Therefore, it is not desirable to choose Ext2 for any server that needs high availability. However, because Ext2 does not maintain a journal and uses less memory, it is sometimes faster than other file systems.

Easy Upgradability

Because Ext3 is based on the Ext2 code and shares its on-disk format and its metadata format, upgrades from Ext2 to Ext3 are very easy.

1.5 Ext3

Ext3 was designed by Stephen Tweedie. Unlike all other next-generation file systems, Ext3 does not follow a completely new design principle. It is based on Ext2. These two file systems are very closely related to each other. An Ext3 file system can be easily built on top of an Ext2 file system. The most important difference between Ext2 and Ext3 is that Ext3 supports journaling. In summary, Ext3 has three major advantages to offer:

1.5.1 Easy and Highly Reliable Upgrades from Ext2

The code for Ext2 is the strong foundation on which Ext3 could become a highly acclaimed next-generation file system. Its reliability and solidity are elegantly combined in Ext3 with the advantages of a journaling file system. Unlike transitions to other journaling file systems, such as ReiserFS or XFS, which can be quite tedious (making backups of the entire file system and re-creating it from scratch), a transition to Ext3 is a matter of minutes. It is also very safe, because re-creating an entire file system from scratch might not work flawlessly. Considering the number of existing Ext2 systems that await an upgrade to a journaling file system, you can easily see why Ext3 might be of some importance to many system administrators. Downgrading from Ext3 to Ext2 is as easy as the upgrade. Perform a clean unmount of the Ext3 file system and remount it as an Ext2 file system.

1.5.2 Reliability and Performance

Some other journaling file systems follow the metadata-only journaling approach. This means your metadata is always kept in a consistent state, but this cannot be automatically guaranteed for the file system data itself. Ext3 is designed to take care of both metadata and data. The degree of care can be customized. Enabling Ext3 in the data=journal mode offers maximum security (data integrity), but can slow down the system because both metadata and data are journaled. A relatively new approach is to use the data=ordered mode, which ensures both data and metadata integrity, but uses journaling only for metadata. The file system driver collects all data blocks that correspond to one metadata update. These data blocks are written to disk before the metadata is updated. As a result, consistency is achieved for metadata and data without sacrificing performance. A third option to use is data=writeback, which allows data to be written to the main file system after its metadata has been committed to the journal. This option is often considered the best in performance. It can, however, allow old data to reappear in files after crash and recovery while internal file system integrity is maintained. Ext3 uses the data=ordered option as the default.

1.5.3 Converting an Ext2 File System into Ext3

To convert an Ext2 file system to Ext3:

  1. Create an Ext3 journal by running tune2fs -j as the root user.

    This creates an Ext3 journal with the default parameters.

    To specify how large the journal should be and on which device it should reside, run tune2fs -J instead together with the desired journal options size= and device=. More information about the tune2fs program is available in the tune2fs man page.

  2. Edit the file /etc/fstab as the root user to change the file system type specified for the corresponding partition from ext2 to ext3, then save the changes.

    This ensures that the Ext3 file system is recognized as such. The change takes effect after the next reboot.

  3. To boot a root file system that is set up as an Ext3 partition, add the modules ext3 and jbd in the initrd. Do so by

    1. adding the following line to /etc/dracut.conf.d/01-dist.conf:

      force_drivers+="ext3 jbd"
    2. and running the dracut -f command.

  4. Reboot the system.

1.5.4 Ext3 File System Inode Size and Number of Inodes

An inode stores information about the file and its block location in the file system. To allow space in the inode for extended attributes and ACLs, the default inode size for Ext3 was increased from 128 bytes on SLES 10 to 256 bytes on SLES 11. As compared to SLES 10, when you make a new Ext3 file system on SLES 11, the default amount of space preallocated for the same number of inodes is doubled, and the usable space for files in the file system is reduced by that amount. Thus, you must use larger partitions to accommodate the same number of inodes and files than were possible for an Ext3 file system on SLES 10.

When you create a new Ext3 file system, the space in the inode table is preallocated for the total number of inodes that can be created. The bytes-per-inode ratio and the size of the file system determine how many inodes are possible. When the file system is made, an inode is created for every bytes-per-inode bytes of space:

number of inodes = total size of the file system divided by the number of bytes per inode

The number of inodes controls the number of files you can have in the file system: one inode for each file. To address the increased inode size and reduced usable space available, the default for the bytes-per-inode ratio was increased from 8192 bytes on SLES 10 to 16384 bytes on SLES 11. The doubled ratio means that the number of files that can be created is one-half of the number of files possible for an Ext3 file system on SLES 10.

Important
Important: Changing the Inode Size of an Existing Ext3 File System

After the inodes are allocated, you cannot change the settings for the inode size or bytes-per-inode ratio. No new inodes are possible without re-creating the file system with different settings, or unless the file system gets extended. When you exceed the maximum number of inodes, no new files can be created on the file system until some files are deleted.

When you make a new Ext3 file system, you can specify the inode size and bytes-per-inode ratio to control inode space usage and the number of files possible on the file system. If the blocks size, inode size, and bytes-per-inode ratio values are not specified, the default values in the /etc/mked2fs.conf file are applied. For information, see the mke2fs.conf(5) man page.

Use the following guidelines:

  • Inode size:  The default inode size is 256 bytes. Specify a value in bytes that is a power of 2 and equal to 128 or larger in bytes and up to the block size, such as 128, 256, 512, and so on. Use 128 bytes only if you do not use extended attributes or ACLs on your Ext3 file systems.

  • Bytes-per-inode ratio:  The default bytes-per-inode ratio is 16384 bytes. Valid bytes-per-inode ratio values must be a power of 2 equal to 1024 or greater in bytes, such as 1024, 2048, 4096, 8192, 16384, 32768, and so on. This value should not be smaller than the block size of the file system, because the block size is the smallest chunk of space used to store data. The default block size for the Ext3 file system is 4 KB.

    In addition, you should consider the number of files and the size of files you need to store. For example, if your file system will have many small files, you can specify a smaller bytes-per-inode ratio, which increases the number of inodes. If your file system will have very large files, you can specify a larger bytes-per-inode ratio, which reduces the number of possible inodes.

    Generally, it is better to have too many inodes than to run out of them. If you have too few inodes and very small files, you could reach the maximum number of files on a disk that is practically empty. If you have too many inodes and very large files, you might have free space reported but be unable to use it because you cannot create new files in space reserved for inodes.

If you do not use extended attributes or ACLs on your Ext3 file systems, you can restore the SLES 10 behavior specifying 128 bytes as the inode size and 8192 bytes as the bytes-per-inode ratio when you make the file system. Use any of the following methods to set the inode size and bytes-per-inode ratio:

  • Modifying the default settings for all new Ext3 files:  In a text editor, modify the defaults section of the /etc/mke2fs.conf file to set the inode_size and inode_ratio to the desired default values. The values apply to all new Ext3 file systems. For example:

    blocksize = 4096
    inode_size = 128
    inode_ratio = 8192
  • At the command line:  Pass the inode size (-I 128) and the bytes-per-inode ratio (-i 8192) to the mkfs.ext3(8) command or the mke2fs(8) command when you create a new Ext3 file system. For example, use either of the following commands:

    sudo mkfs.ext3 -b 4096 -i 8092 -I 128 /dev/sda2
    sudo mke2fs -t ext3 -b 4096 -i 8192 -I 128 /dev/sda2
  • During installation with YaST:  Pass the inode size and bytes-per-inode ratio values when you create a new Ext3 file system during the installation. In the YaST Partitioner on the Edit Partition page under Formatting Options, select Format partitionExt3, then click Options. In the File system options dialog, select the desired values from the Block Size in Bytes, Bytes-per-inode, and Inode Size drop-down box.

    For example, select 4096 for the Block Size in Bytes drop-down box, select 8192 from the Bytes per inode drop-down box, select 128 from the Inode Size drop-down box, then click OK.

  • During installation with AutoYaST:  In an AutoYaST profile, you can use the fs_options tag to set the opt_bytes_per_inode ratio value of 8192 for -i and the opt_inode_density value of 128 for -I:

    <partitioning config:type="list">
      <drive>
        <device>/dev/sda</device>
        <initialize config:type="boolean">true</initialize>
        <partitions config:type="list">
          <partition>
            <filesystem config:type="symbol">ext3</filesystem>
            <format config:type="boolean">true</format>
            <fs_options>
              <opt_bytes_per_inode>
                <option_str>-i</option_str>
                <option_value>8192</option_value>
              </opt_bytes_per_inode>
              <opt_inode_density>
                <option_str>-I</option_str>
                <option_value>128</option_value>
              </opt_inode_density>
            </fs_options>
            <mount>/</mount>
            <partition_id config:type="integer">131</partition_id>
            <partition_type>primary</partition_type>
            <size>25G</size>
          </partition>
        </partitions>
      </drive>
    <partitioning>

For information, see http://www.suse.com/support/kb/doc.php?id=7009075 (SLES11 ext3 partitions can only store 50% of the files that can be stored on SLES10 [Technical Information Document 7009075]).

1.6 Ext4

In 2006, Ext4 started as a fork from Ext3. It eliminates some storage limitations of Ext3 by supporting volumes with a size of up to 1 exbibyte, files with a size of up to 16 tebibytes and an unlimited number of subdirectories. It also introduces several performance enhancements such as delayed block allocation and a much faster file system checking routine. Ext4 is also more reliable by supporting journal checksums and by providing time stamps measured in nanoseconds. Ext4 is fully backward compatible to Ext2 and Ext3—both file systems can be mounted as Ext4.

1.7 ReiserFS

Officially one of the key features of the 2.4 kernel release, ReiserFS has been available as a kernel patch for 2.2.x SUSE kernels since version 6.4. ReiserFS was designed by Hans Reiser and the Namesys development team. It has proven itself to be a powerful alternative to Ext2. Its key assets are better disk space usage, better disk access performance, faster crash recovery, and reliability through data journaling.

Important
Important: Support of ReiserFS in SUSE Linux Enterprise Server 12

Existing ReiserFS partitions are supported for the lifetime of SUSE Linux Enterprise Server 12 specifically for migration purposes. Support for creating new ReiserFS file systems has been removed starting with SUSE Linux Enterprise Server 12.

1.8 Other Supported File Systems

Table 1.1, “File System Types in Linux” summarizes some other file systems supported by Linux. They are supported mainly to ensure compatibility and interchange of data with different kinds of media or foreign operating systems.

Table 1.1: File System Types in Linux

File System Type

Description

cramfs

Compressed ROM file system: A compressed read-only file system for ROMs.

hpfs

High Performance File System: The IBM OS/2 standard file system. Only supported in read-only mode.

iso9660

Standard file system on CD-ROMs.

minix

This file system originated from academic projects on operating systems and was the first file system used in Linux. Today, it is used as a file system for floppy disks.

msdos

fat, the file system originally used by DOS, is today used by various operating systems.

nfs

Network File System: Here, data can be stored on any machine in a network and access might be granted via a network.

ntfs

Windows NT file system; read-only.

smbfs

Server Message Block is used by products such as Windows to enable file access over a network.

sysv

Used on SCO Unix, Xenix, and Coherent (commercial Unix systems for PCs).

ufs

Used by BSD, SunOS, and NextStep. Only supported in read-only mode.

umsdos

Unix on MS-DOS: Applied on top of a standard fat file system, achieves Unix functionality (permissions, links, long file names) by creating special files.

vfat

Virtual FAT: Extension of the fat file system (supports long file names).

1.9 Large File Support in Linux

Originally, Linux supported a maximum file size of 2 GiB (231 bytes). Unless a file system comes with large file support, the maximum file size on a 32-bit system is 2 GiB.

Currently, all of our standard file systems have LFS (large file support), which gives a maximum file size of 263 bytes in theory. Table 1.2, “Maximum Sizes of Files and File Systems (On-Disk Format, 4 KiB Block Size)” offers an overview of the current on-disk format limitations of Linux files and file systems. The numbers in the table assume that the file systems are using 4 KiB block size, which is a common standard. When using different block sizes, the results are different. The maximum file sizes in Table 1.2, “Maximum Sizes of Files and File Systems (On-Disk Format, 4 KiB Block Size)” can be larger than the file system's actual size when using sparse blocks.

Note
Note: Binary Multiples

In this document: 1024 Bytes = 1 KiB; 1024 KiB = 1 MiB; 1024 MiB = 1 GiB; 1024 GiB = 1 TiB; 1024 TiB = 1 PiB; 1024 PiB = 1 EiB (see also NIST: Prefixes for Binary Multiples.

Table 1.2: Maximum Sizes of Files and File Systems (On-Disk Format, 4 KiB Block Size)

File System (4 KiB Block Size)

Maximum File System Size

Maximum File Size

Btrfs

16 EiB

16 EiB

Ext3

16 TiB

2 TiB

Ext4

1 EiB

16 TiB

OCFS2 (a cluster-aware file system available in the High Availability Extension)

16 TiB

1 EiB

ReiserFS v3.6

16 TiB

1 EiB

XFS

8 EiB

8 EiB

NFSv2 (client side)

8 EiB

2 GiB

NFSv3/NFSv4 (client side)

8 EiB

8 EiB

Important
Important: Limitations

Table 1.2, “Maximum Sizes of Files and File Systems (On-Disk Format, 4 KiB Block Size)” describes the limitations regarding the on-disk format. The Linux kernel imposes its own limits on the size of files and file systems handled by it. These are as follows:

File Size

On 32-bit systems, files cannot exceed 2 TiB (241 bytes).

File System Size

File systems can be up to 273 bytes in size. However, this limit is still out of reach for the currently available hardware.

1.10 Linux Kernel Storage Limitations

Table 1.3, “Storage Limitations” summarizes the kernel limits for storage associated with SUSE Linux Enterprise Server.

Table 1.3: Storage Limitations

Storage Feature

Limitation

Maximum number of LUNs supported

16384 LUNs per target.

Maximum number of paths per single LUN

No limit by default. Each path is treated as a normal LUN.

The actual limit is given by the number of LUNs per target and the number of targets per HBA (16777215 for a Fibre Channel HBA).

Maximum number of HBAs

Unlimited. The actual limit is determined by the amount of PCI slots of the system.

Maximum number of paths with device-mapper-multipath (in total) per operating system

Approximately 1024. The actual number depends on the length of the device number strings. It is a compile-time variable within multipath-tools, which can be raised if this limit poses a problem.

Maximum size per block device

Up to 8 EiB.

1.11 Troubleshooting File Systems

This section describes some known issues and possible solutions for file systems.

1.11.1 Btrfs Error: No space is left on device

The root (/) partition using the Btrfs file system stops accepting data. You receive the error No space left on device.

See the following sections for information about possible causes and prevention of this issue.

1.11.1.1 Disk Space Consumed by Snapper Snapshots

If Snapper is running for the Btrfs file system, the No space left on device problem is typically caused by having too much data stored as snapshots on your system.

You can remove some snapshots from Snapper, however, the snapshots are not deleted immediately and might not free up as much space as you need.

To delete files from Snapper:

  1. Open a terminal console.

  2. At the command prompt, enter btrfs filesystem show, for example:

    tux > sudo btrfs filesystem show
    Label: none uuid: 40123456-cb2c-4678-8b3d-d014d1c78c78
     Total devices 1 FS bytes used 20.00GB
     devid 1 size 20.00GB used 20.00GB path /dev/sda3
  3. Enter

    sudo btrfs fi balance start MOUNTPOINT -dusage=5

    This command attempts to relocate data in empty or near-empty data chunks, allowing the space to be reclaimed and reassigned to metadata. This can take a while (many hours for 1 TB) although the system is otherwise usable during this time.

  4. List the snapshots in Snapper. Enter

    sudo snapper -c root list
  5. Delete one or more snapshots from Snapper. Enter

    sudo snapper -c root delete SNAPSHOT_NUMBER(S)

    Ensure that you delete the oldest snapshots first. The older a snapshot is, the more disk space it occupies.

To help prevent this problem, you can change the Snapper cleanup algorithms. See Section 7.5.1.2, “Cleanup-algorithms” for details. The configuration values controlling snapshot cleanup are EMPTY_*, NUMBER_*, and TIMELINE_*.

If you use Snapper with Btrfs on the file system disk, it is advisable to reserve twice the amount of disk space than the standard storage proposal. The YaST Partitioner automatically proposes twice the standard disk space in the Btrfs storage proposal for the root file system.

1.11.1.2 Disk Space Consumed by Log, Crash, and Cache Files

If the system disk is filling up with data, you can try deleting files from /var/log, /var/crash, /var/lib/systemd/coredump and /var/cache.

The Btrfs root file system subvolumes /var/log, /var/crash and /var/cache can use all of the available disk space during normal operation, and cause a system malfunction. To help avoid this situation, SUSE Linux Enterprise Server offers Btrfs quota support for subvolumes. See Section 1.2.5, “Btrfs Quota Support for Subvolumes” for details.

On test and development machines, especially if you have frequent crashes of applications, you may also want to have a look at /var/lib/systemd/coredump where the coredumps are stored.

1.11.2 Freeing Unused File System Blocks

On solid-state drives (SSDs) and thinly provisioned volumes it is useful to trim blocks not in use by the file system. SUSE Linux Enterprise Server fully supports unmap or trim operations on all file systems supporting these methods.

The recommended way to trim a supported file system (except Btrfs) on SUSE Linux Enterprise Server is to run /sbin/wiper.sh. Make sure to read /usr/share/doc/packages/hdparm/README.wiper before running this script. For most desktop and server systems the sufficient trimming frequency is once a week. Mounting a file system with -o discard comes with a performance penalty and may negatively affect the lifetime of SSDs and is not recommended.

Warning
Warning: Do Not Use wiper.sh on Btrfs

The wiper.sh script trims read-write mounted ext4 and xfs file systems, and for read-only mounted/unmounted ext2, ext3, ext4, and xfs file systems. Do not use wiper.sh on the Btrfs file system as it may damage your data. Instead, use /usr/share/btrfsmaintenance/btrfs-trim.sh which is part of the btrfsmaintenance package.

1.12 Additional Information

Each of the file system projects described above maintains its own home page on which to find mailing list information, further documentation, and FAQs:

A comprehensive multi-part tutorial about Linux file systems can be found at IBM developerWorks in the Advanced File System Implementor’s Guide (https://www.ibm.com/developerworks/linux/library/l-fs/).

An in-depth comparison of file systems (not only Linux file systems) is available from the Wikipedia project in Comparison of File Systems (http://en.wikipedia.org/wiki/Comparison_of_file_systems#Comparison).

2 Resizing File Systems

  • Filename: storage_fs-resizing.xml
  • ID: cha.resize_fs

Resizing file systems—not to be confused with resizing partitions or volumes—can be used to make space available on physical volumes or to use additional space available on a physical volume.

2.1 Use Cases

It is strongly recommended to use the YaST Partitioner to resize partitions or logical volumes. When doing so, the file system will automatically be adjusted to the new size of the partition or volume. However, there are some cases where you need to resize the file system manually, because they are not supported by YaST:

  • After having resized a virtual disk of a VM Guest.

  • After having resized a volume from a network-attached storage.

  • After having manually resized partitions (for example by using fdisk or parted) or logical volumes (for example by using lvresize).

  • When wanting to shrink Btrfs file systems (as of SUSE Linux Enterprise Server 12, YaST only supports growing Btrfs file systems).

2.2 Guidelines for Resizing

Resizing any file system involves some risks that can potentially result in losing data.

Warning
Warning: Back Up your Data

To avoid data loss, ensure that you back up your data before you begin any resizing task.

Consider the following guidelines when planning to resize a file system.

2.2.1 File Systems that Support Resizing

The file system must support resizing to take advantage of increases in available space for the volume. In SUSE Linux Enterprise Server, file system resizing utilities are available for file systems Ext2, Ext3, Ext4, and ReiserFS. The utilities support increasing and decreasing the size as follows:

Table 2.1: File System Support for Resizing

File System

Utility

Increase Size (Grow)

Decrease Size (Shrink)

Btrfs

btrfs filesystem resize

Online

Online

XFS

xfs_growfs

Online

Not supported

Ext2

resize2fs

Online or offline

Offline only

Ext3

resize2fs

Online or offline

Offline only

Ext4

resize2fs

Online or offline

Offline only

ReiserFS

resize_reiserfs

Online or offline

Offline only

2.2.2 Increasing the Size of a File System

You can grow a file system to the maximum space available on the device, or specify an exact size. Ensure that you grow the size of the device or logical volume before you attempt to increase the size of the file system.

When specifying an exact size for the file system, ensure that the new size satisfies the following conditions:

  • The new size must be greater than the size of the existing data; otherwise, data loss occurs.

  • The new size must be equal to or less than the current device size because the file system size cannot extend beyond the space available.

2.2.3 Decreasing the Size of a File System

When decreasing the size of the file system on a device, ensure that the new size satisfies the following conditions:

  • The new size must be greater than the size of the existing data; otherwise, data loss occurs.

  • The new size must be equal to or less than the current device size because the file system size cannot extend beyond the space available.

If you plan to also decrease the size of the logical volume that holds the file system, ensure that you decrease the size of the file system before you attempt to decrease the size of the device or logical volume.

Important
Important: XFS

Decreasing the size of a file system formatted with XFS is not possible, since such a feature is not supported by XFS.

2.3 Changing the Size of a Btrfs File System

The size of a Btrfs file system can be changed by using the btrfs filesystem resize command when the file system is mounted. Increasing and decreasing the size are both supported while the file system is mounted.

  1. Open a terminal console.

  2. Make sure the file system you want to change is mounted.

  3. Change the size of the file system using the btrfs filesystem resize command with one of the following methods:

    • To extend the file system size to the maximum available size of the device, enter

      sudo btrfs filesystem resize max /mnt
    • To extend the file system to a specific size, enter

      sudo btrfs filesystem resize SIZE /mnt

      Replace SIZE with the desired size in bytes. You can also specify units on the value, such as 50000K (kilobytes), 250M (megabytes), or 2G (gigabytes). Alternatively, you can specify an increase or decrease to the current size by prefixing the value with a plus (+) or a minus (-) sign, respectively:

      sudo btrfs filesystem resize +SIZE /mnt
      sudo btrfs filesystem resize -SIZE /mnt
  4. Check the effect of the resize on the mounted file system by entering

    df -h

    The Disk Free (df) command shows the total size of the disk, the number of blocks used, and the number of blocks available on the file system. The -h option prints sizes in human-readable format, such as 1K, 234M, or 2G.

2.4 Changing the Size of an XFS File System

The size of an XFS file system can be increased by using the xfs_growfs command when the file system is mounted. Reducing the size of an XFS file system is not possible.

  1. Open a terminal console.

  2. Make sure the file system you want to change is mounted.

  3. Increase the size of the file system using the xfs_growfs command. The following example expands the size of the file system to the maximum value available. See man 8 xfs_growfs for more options.

    sudo xfs_growfs -d /mnt
  4. Check the effect of the resize on the mounted file system by entering

    df -h

    The Disk Free (df) command shows the total size of the disk, the number of blocks used, and the number of blocks available on the file system. The -h option prints sizes in human-readable format, such as 1K, 234M, or 2G.

2.5 Changing the Size of an Ext2, Ext3, or Ext4 File System

The size of Ext2, Ext3, and Ext4 file systems can be increased by using the resize2fs command, regardless of whether the respective partition is mounted or not. To decrease the size of an Ext file system it needs to be unmounted.

  1. Open a terminal console.

  2. If the file system size should be decreased, unmount it.

  3. Change the size of the file system using one of the following methods:

    • To extend the file system size to the maximum available size of the device called /dev/sda1, enter

      sudo resize2fs /dev/sda1

      If a size parameter is not specified, the size defaults to the size of the partition.

    • To change the file system to a specific size, enter

      sudo resize2fs /dev/sda1 SIZE

      The SIZE parameter specifies the requested new size of the file system. If no units are specified, the unit of the size parameter is the block size of the file system. Optionally, the size parameter can be suffixed by one of the following unit designators: s for 512 byte sectors; K for kilobytes (1 kilobyte is 1024 bytes); M for megabytes; or G for gigabytes.

    Wait until the resizing is completed before continuing.

  4. If the file system is not mounted, mount it now.

  5. Check the effect of the resize on the mounted file system by entering

    df -h

    The Disk Free (df) command shows the total size of the disk, the number of blocks used, and the number of blocks available on the file system. The -h option prints sizes in human-readable format, such as 1K, 234M, or 2G.

2.6 Changing the Size of a Reiser File System

A ReiserFS file system can be increased in size while mounted or unmounted. To decrease its size it needs to be unmounted.

  1. Open a terminal console.

  2. If you want to decrease the size of the file system, unmount it in case it is mounted.

  3. Change the size of the file system on the device called /dev/sda2, using one of the following methods:

    • To extend the file system size to the maximum available size of the device, enter

      sudo resize_reiserfs /dev/sda2

      When no size is specified, this increases the volume to the full size of the partition.

    • To extend the file system to a specific size, enter

      sudo resize_reiserfs -s SIZE /dev/sda2

      Replace SIZE with the desired size in bytes. You can also specify units on the value, such as 50000K (kilobytes), 250M (megabytes), or 2G (gigabytes). Alternatively, you can specify an increase or decrease to the current size by prefixing the value with a plus (+) or minus (-) sign, respectively:

      sudo resize_reiserfs -s +SIZE /dev/sda2
      sudo resize_reiserfs -s -SIZE /dev/sda2

    Wait until the resizing is completed before continuing.

  4. If the file system is not mounted, mount it now.

  5. Check the effect of the resize on the mounted file system by entering

    df -h

    The Disk Free (df) command shows the total size of the disk, the number of blocks used, and the number of blocks available on the file system. The -h option prints sizes in human-readable format, such as 1K, 234M, or 2G.

3 Using UUIDs to Mount Devices

  • Filename: storage_uuids.xml
  • ID: cha.uuid

This section describes the use of UUIDs (Universally Unique Identifiers) instead of device names (such as /dev/sda1) to identify file system devices. Starting with SUSE Linux Enterprise Server 12, UUIDs are used by default in the boot loader file and the /etc/fstab file.

3.1 Persistent Device Names with udev

Starting with Linux kernel 2.6, udev provides a user space solution for the dynamic /dev directory, with persistent device naming. As part of the hotplug system, udev is executed if a device is added to or removed from the system.

A list of rules is used to match against specific device attributes. The udev rules infrastructure (defined in the /etc/udev/rules.d directory) provides stable names for all disk devices, regardless of their order of recognition or the connection used for the device. The udev tools examine every appropriate block device that the kernel creates to apply naming rules based on certain buses, drive types, or file systems. For information about how to define your own rules for udev, see Writing udev Rules.

Along with the dynamic kernel-provided device node name, udev maintains classes of persistent symbolic links pointing to the device in the /dev/disk directory, which is further categorized by the by-id, by-label, by-path, and by-uuid subdirectories.

Note
Note: UUID Generators

Other programs besides udev, such as LVM or md, might also generate UUIDs, but they are not listed in /dev/disk.

3.2 Understanding UUIDs

A UUID (Universally Unique Identifier) is a 128-bit number for a file system that is unique on both the local system and across other systems. It is randomly generated with system hardware information and time stamps as part of its seed. UUIDs are commonly used to uniquely tag devices.

Using non-persistent traditional device names such as /dev/sda1 may render the system unbootable when adding storage. For example, if root (/) is assigned to /dev/sda1, it might be reassigned to /dev/sdg1 after a SAN has been attached or additional hard disks have been applied to the system. In this case the boot loader configuration and the /etc/fstab file need to be adjusted, otherwise the system will no longer boot.

One way to avoid this problem is to use the UUID in the boot loader and /etc/fstab files for the boot device. This is the default in SUSE Linux Enterprise since version 12. The UUID is a property of the file system and can change if you reformat the drive. Other alternatives to using UUIDs of device names would be to identify devices by ID or label.

You can also use the UUID as criterion for assembling and activating software RAID devices. When a RAID is created, the md driver generates a UUID for the device, and stores the value in the md superblock.

You can find the UUID for any block device in the /dev/disk/by-uuid directory. For example, a UUID entry looks like this:

tux > ls -og /dev/disk/by-uuid/
lrwxrwxrwx 1 10 Dec  5 07:48 e014e482-1c2d-4d09-84ec-61b3aefde77a -> ../../sda1

3.3 Additional Information

For more information about using udev for managing devices, see Chapter 21, Dynamic Kernel Device Management with udev.

For more information about udev commands, see man 7 udev.

4 Multi-tier Caching for Block Device Operations

  • Filename: storage_multitier-caching.xml
  • ID: cha.multitiercache

A multi-tier cache is a replicated/distributed cache that consists of at least two tiers: one is represented by slower but cheaper rotational block devices (hard disks), while the other is more expensive but performs faster data operations (for example SSD flash disks).

SUSE Linux Enterprise Server implements two different solutions for caching between flash and rotational devices: bcache and lvmcache.

4.1 General Terminology

This section explains several terms often used when describing cache related features:

Migration

Movement of the primary copy of a logical block from one device to the other.

Promotion

Migration from the slow device to the fast device.

Demotion

Migration from the fast device to the slow device.

Origin device

The big and slower block device. It always contains a copy of the logical block, which may be out of date or kept in synchronization with the copy on the cache device (depending on policy).

Cache device

The small and faster block device.

Metadata device

A small device that records which blocks are in the cache, which are dirty, and extra hints for use by the policy object. This information could be put on the cache device as well, but having it separate allows the volume manager to configure it differently, for example as a mirror for extra robustness. The metadata device may only be used by a single cache device.

Dirty block

If some process writes to a block of data which is placed in the cache, the cached block is marked as dirty because it was overwritten in the cache and needs to be written back to the original device.

Cache miss

A request for I/O operations is pointed to the cached device's cache first. If it cannot find the requested values, it looks in the device itself, which is slow. This is called a cache miss.

Cache hit

When a requested value is found in the cached device's cache, it is served fast. This is called a cache hit.

Cold cache

Cache that holds no values (is empty) and causes cache misses. As the cached block device operations progress, it gets filled with data and becomes warm.

Warm cache

Cache that already holds some values and is likely to result in cache hits.

4.2 Caching Modes

Following are the basic caching modes that multi-tier caches use: write-back, write-through, write-around and pass-through.

write-back

Data written to a block that is cached go to the cache only, and the block is marked dirty. This is the default caching mode.

write-through

Writing to a cached block will not complete until it has hit both the origin and cache devices. Clean blocks remain clean with write-through cache.

write-around

A similar technique to write-through cache, but write I/O is written directly to a permanent storage, bypassing the cache. This can prevent the cache being flooded with write I/O that will not subsequently be re-read, but the disadvantage is that a read request for recently written data will create a 'cache miss' and needs to be read from slower bulk storage and experience higher latency.

pass-through

To enable the pass-through mode, the cache needs to be clean. Reading is served from the origin device bypassing the cache. Writing is forwarded to the origin device and 'invalidates' the cache block. Pass-through allows a cache device activation without having to care about data coherency, which is maintained. The cache will gradually become cold as writing takes place. If you can verify the coherency of the cache later, or establish it by using the invalidate_cblocks message, you can switch the cache device to write-through or write-back mode while it is still warm. Otherwise, you can discard the cache contents before switching to the desired caching mode.

4.3 bcache

bcache is a Linux kernel block layer cache. It allows one or more fast disk drives (such as SSDs) to act as a cache for one or more slower hard disks. bcache supports write-through and write-back, and is independent of the file system used. By default it caches random reads and writes only, which SSDs excel at. It is suitable for desktops, servers, and high end storage arrays as well.

4.3.1 Main Features

  • A single cache device can be used to cache an arbitrary number of backing devices. Backing devices can be attached and detached at runtime, while mounted and in use.

  • Recovers from unclean shutdowns—writes are not completed until the cache is consistent with regard to the backing device.

  • Throttles traffic to the SSD if it becomes congested.

  • Highly efficient write-back implementation. Dirty data is always written out in sorted order.

  • Stable and reliable—in production use.

4.3.2 Setting Up a bcache Device

This section describes steps to set up and manage a bcache device.

  1. Install the bcache-tools package:

    sudo zypper in bcache-tools
  2. Create a backing device (typically a mechanical drive). The backing device can be a whole device, a partition, or any other standard block device.

    sudo make-bcache -B /dev/sdb
  3. Create a cache device (typically an SSD disk).

    sudo make-bcache -C /dev/sdc

    In this example, the default block and bucket sizes of 512 B and 128 KB are used. The block size should match the backing device's sector size which will usually be either 512 or 4k. The bucket size should match the erase block size of the caching device with the intention of reducing write amplification. For example, using a hard disk with 4k sectors and an SSD with an erase block size of 2 MB this command would look as follows:

    sudo make-bcache --block 4k --bucket 2M -C /dev/sdc
    Tip
    Tip: Multi-Device Support

    make-bcache can prepare and register multiple backing devices and a cache device at the same time. In this case you do not need to manually attach the cache device to the backing device afterward:

    sudo make-bcache -B /dev/sda /dev/sdb -C /dev/sdc
  4. bcache devices show up as

    /dev/bcacheN

    and as

    /dev/bcache/by-uuid/UUID
    /dev/bcache/by-label/LABEL

    You can normally format and mount bcache devices as usual:

    mkfs.ext4 /dev/bcache0
    mount /dev/bcache0 /mnt

    You can control bcache devices through sysfs at /sys/block/bcacheN/bcache.

  5. After both the cache and backing devices are registered, you need to attach the backing device to the related cache set to enable caching:

    echo CACHE_SET_UUID > /sys/block/bcache0/bcache/attach

    where CACHE_SET_UUID is found in /sys/fs/bcache.

  6. By default bcache uses a pass-through caching mode. To change it to for example write-back, run

    echo writeback > /sys/block/bcache0/bcache/cache_mode

4.3.3 bcache Configuration Using sysfs

bcache devices use the sysfs interface to store their runtime configuration values. This way you can change bcache backing and cache disks' behavior or see their usage statistics.

For the complete list of bcache sysfs parameters, see the contents of the /usr/src/linux/Documentation/bcache.txt file, mainly the SYSFS - BACKING DEVICE, SYSFS - BACKING DEVICE STATS, and SYSFS - CACHE DEVICE sections.

4.4 lvmcache

lvmcache is a caching mechanism consisting of logical volumes (LVs). It uses the dm-cache kernel driver and supports write-through (default) and write-back caching modes. lvmcache improves performance of a large and slow LV by dynamically migrating some of its data to a faster and smaller LV. For more information on LVM, see Part II, “Logical Volumes (LVM)”.

LVM refers to the small, fast LV as a cache pool LV. The large, slow LV is called the origin LV. Because of requirements from dm-cache, LVM further splits the cache pool LV into two devices: the cache data LV and cache metadata LV. The cache data LV is where copies of data blocks are kept from the origin LV to increase speed. The cache metadata LV holds the accounting information that specifies where data blocks are stored.

4.4.1 Configuring lvmcache

This section describes steps to create and configure LVM based caching.

  1. Create the origin LV. Create a new LV or use an existing LV to become the origin LV:

    lvcreate -n ORIGIN_LV -L 100G vg /dev/SLOW_DEV
  2. Create the cache data LV. This LV will hold data blocks from the origin LV. The size of this LV is the size of the cache and will be reported as the size of the cache pool LV.

    lvcreate -n CACHE_DATA_LV -L 10G vg /dev/FAST
  3. Create the cache metadata LV. This LV will hold cache pool metadata. The size of this LV should be approximately 1000 times smaller than the cache data LV, with a minimum size of 8MB.

    lvcreate -n CACHE_METADATA_LV -L 12M vg /dev/FAST

    List the volumes you have created so far:

    lvs -a vg
    LV                VG   Attr        LSize   Pool Origin
    cache_data_lv     vg   -wi-a-----  10.00g
    cache_metadata_lv vg   -wi-a-----  12.00m
    origin_lv         vg   -wi-a----- 100.00g
  4. Create a cache pool LV. Combine the data and metadata LVs into a cache pool LV. You can set the cache pool LV's behavior at the same time.

    CACHE_POOL_LV takes the name of CACHE_DATA_LV.

    CACHE_DATA_LV is renamed to CACHE_DATA_LV_cdata and becomes hidden.

    CACHE_META_LV is renamed to CACHE_DATA_LV_cmeta and becomes hidden.

    lvconvert --type cache-pool \
     --poolmetadata vg/cache_metadata_lv vg/cache_data_lv
    lvs -a vg
    LV                     VG   Attr       LSize   Pool Origin
    cache_data_lv          vg   Cwi---C---  10.00g
    [cache_data_lv_cdata]  vg   Cwi-------  10.00g
    [cache_data_lv_cmeta]  vg   ewi-------  12.00m
    origin_lv              vg   -wi-a----- 100.00g
  5. Create a cache LV. Create a cache LV by linking the cache pool LV to the origin LV.

    The user accessible cache LV takes the name of the origin LV, while the origin LV becomes a hidden LV renamed to ORIGIN_LV_corig.

    CacheLV takes the name of ORIGIN_LV.

    ORIGIN_LV is renamed to ORIGIN_LV_corig and becomes hidden.

    lvconvert --type cache --cachepool vg/cache_data_lv vg/origin_lv
    lvs -a vg
    LV              VG   Attr       LSize   Pool   Origin
    cache_data_lv          vg   Cwi---C---  10.00g
    [cache_data_lv_cdata]  vg   Cwi-ao----  10.00g
    [cache_data_lv_cmeta]  vg   ewi-ao----  12.00m
    origin_lv              vg   Cwi-a-C--- 100.00g cache_data_lv [origin_lv_corig]
    [origin_lv_corig]      vg   -wi-ao---- 100.00g

4.4.2 Removing a Cache Pool

There are several ways to turn off the LV cache.

4.4.2.1 Detach a Cache Pool LV from a Cache LV

You can disconnect a cache pool LV from a cache LV, leaving an unused cache pool LV and an uncached origin LV. Data are written back from the cache pool to the origin LV when necessary.

lvconvert --splitcache vg/origin_lv

4.4.2.2 Removing a Cache Pool LV without Removing its Origin LV

This writes back data from the cache pool to the origin LV when necessary, then removes the cache pool LV, leaving the uncached origin LV.

lvremove vg/cache_data_lv

An alternative command that also disconnects the cache pool from the cache LV, and deletes the cache pool:

lvconvert --uncache vg/origin_lv

4.4.2.3 Removing Both the Origin LV and the Cache Pool LV

Removing a cache LV removes both the origin LV and the linked cache pool LV.

lvremove vg/origin_lv

4.4.2.4 For More Information

You can find more lvmcache related topics, such as supported cache modes, redundant sub-logical volumes, cache policy, or converting existing LVs to cache types, in the lvmcache manual page (man 7 lvmcache).

Part II Logical Volumes (LVM)

5 LVM Configuration

This chapter describes the principles behind Logical Volume Manager (LVM) and its basic features that make it useful under many circumstances. The YaST LVM configuration can be reached from the YaST Expert Partitioner. This partitioning tool enables you to edit and delete existing partitions and create new ones that should be used with LVM.

6 LVM Volume Snapshots

A Logical Volume Manager (LVM) logical volume snapshot is a copy-on-write technology that monitors changes to an existing volume’s data blocks so that when a write is made to one of the blocks, the block’s value at the snapshot time is copied to a snapshot volume. In this way, a point-in-time copy o…

5 LVM Configuration

  • Filename: storage_lvm.xml
  • ID: cha.lvm
Abstract

This chapter describes the principles behind Logical Volume Manager (LVM) and its basic features that make it useful under many circumstances. The YaST LVM configuration can be reached from the YaST Expert Partitioner. This partitioning tool enables you to edit and delete existing partitions and create new ones that should be used with LVM.

Warning
Warning: Risks

Using LVM might be associated with increased risk, such as data loss. Risks also include application crashes, power failures, and faulty commands. Save your data before implementing LVM or reconfiguring volumes. Never work without a backup.

5.1 Understanding the Logical Volume Manager

LVM enables flexible distribution of hard disk space over several physical volumes (hard disks, partitions, LUNs). It was developed because the need to change the segmentation of hard disk space might arise only after the initial partitioning has already been done during installation. Because it is difficult to modify partitions on a running system, LVM provides a virtual pool (volume group or VG) of storage space from which logical volumes (LVs) can be created as needed. The operating system accesses these LVs instead of the physical partitions. Volume groups can span more than one disk, so that several disks or parts of them can constitute one single VG. In this way, LVM provides a kind of abstraction from the physical disk space that allows its segmentation to be changed in a much easier and safer way than through physical repartitioning.

Figure 5.1, “Physical Partitioning versus LVM” compares physical partitioning (left) with LVM segmentation (right). On the left side, one single disk has been divided into three physical partitions (PART), each with a mount point (MP) assigned so that the operating system can access them. On the right side, two disks have been divided into two and three physical partitions each. Two LVM volume groups (VG 1 and VG 2) have been defined. VG 1 contains two partitions from DISK 1 and one from DISK 2. VG 2 contains the remaining two partitions from DISK 2.

Physical Partitioning versus LVM
Figure 5.1: Physical Partitioning versus LVM

In LVM, the physical disk partitions that are incorporated in a volume group are called physical volumes (PVs). Within the volume groups in Figure 5.1, “Physical Partitioning versus LVM”, four logical volumes (LV 1 through LV 4) have been defined, which can be used by the operating system via the associated mount points (MP). The border between different logical volumes need not be aligned with any partition border. See the border between LV 1 and LV 2 in this example.

LVM features:

  • Several hard disks or partitions can be combined in a large logical volume.

  • Provided the configuration is suitable, an LV (such as /usr) can be enlarged when the free space is exhausted.

  • Using LVM, it is possible to add hard disks or LVs in a running system. However, this requires hotpluggable hardware that is capable of such actions.

  • It is possible to activate a striping mode that distributes the data stream of a logical volume over several physical volumes. If these physical volumes reside on different disks, this can improve the reading and writing performance like RAID 0.

  • The snapshot feature enables consistent backups (especially for servers) in the running system.

Note
Note: LVM and RAID

Even though LVM also supports RAID of 0/1/4/5/6 levels, we recommend to use MD RAID (see Chapter 7, Software RAID Configuration). However, LVM works fine with RAID 0 and 1, as RAID 0 is similar to common logical volume management (individual logical blocks are mapped onto blocks on the physical devices). LVM used on top of RAID 1 can keep track of mirror synchronization and is fully able to manage the synchronization process. With higher RAID levels you need a management daemon that monitors the states of attached disks and can inform administrators if there is a problem in the disk array. LVM includes such a daemon, but in exceptional situations like a device failure, the daemon does not working properly.

Warning
Warning: IBM z Systems: LVM Root File System

If you configure the system with an root file system on LVM or software raid array, you must place /boot on a separate, non-LVM or non-Raid partition, otherwise the system will fail to boot. The recommended size for such a partition is 500 MB and the recommended file system is Ext4.

With these features, using LVM already makes sense for heavily used home PCs or small servers. If you have a growing data stock, as in the case of databases, music archives, or user directories, LVM is especially useful. It allows file systems that are larger than the physical hard disk. However, keep in mind that working with LVM is different from working with conventional partitions.

You can manage new or existing LVM storage objects by using the YaST Partitioner. Instructions and further information about configuring LVM are available in the official LVM HOWTO.

5.2 Creating Volume Groups

An LVM volume group (VG) organizes the Linux LVM partitions into a logical pool of space. You can carve out logical volumes from the available space in the group. The Linux LVM partitions in a group can be on the same or different disks. You can add partitions or entire disks to expand the size of the group.

To use an entire disk, it must not contain any partitions. When using partitions, they must not be mounted. YaST will automatically change their partition type to 0x8E Linux LVM when adding them to a VG.

  1. Launch YaST and open the Partitioner.

  2. In case you need to reconfigure your existing partitioning setup, proceed as follows. Refer to Section 12.1, “Using the YaST Partitioner” for details. Skip this step if you only want to use unused disks or partitions that already exist.

    Warning
    Warning: Physical Volumes on Unpartitioned Disks

    You can use an unpartitioned disk as a physical volume (PV) if that one is not the disk where the operating system is installed and from which it boots.

    As unpartitioned disks appear as unused on the system level, they can easily be overwritten or wrongly accessed.

    1. To use an entire hard disk that already contains partitions, delete all partitions on that disk.

    2. To use a partition that is currently mounted, unmount it.

  3. In the left panel, select Volume Management.

    A list of existing Volume Groups opens in the right panel.

  4. At the lower left of the Volume Management page, click Add › Volume Group.

  5. Define the volume group as follows:

    1. Specify the Volume Group Name.

      If you are creating a volume group at install time, the name system is suggested for a volume group that will contain the SUSE Linux Enterprise Server system files.

    2. Specify the Physical Extent Size.

      The Physical Extent Size defines the size of a physical block in the volume group. All the disk space in a volume group is handled in chunks of this size. Values can be from 1 KB to 16 GB in powers of 2. This value is normally set to 4 MB.

      In LVM1, a 4 MB physical extent allowed a maximum LV size of 256 GB because it supports only up to 65534 extents per LV. LVM2, which is used on SUSE Linux Enterprise Server, does not restrict the number of physical extents. Having many extents has no impact on I/O performance to the logical volume, but it slows down the LVM tools.

      Important
      Important: Physical Extent Sizes

      Different physical extent sizes should not be mixed in a single VG. The extent should not be modified after the initial setup.

    3. In the Available Physical Volumes list, select the Linux LVM partitions that you want to make part of this volume group, then click Add to move them to the Selected Physical Volumes list.

    4. Click Finish.

      The new group appears in the Volume Groups list.

  6. On the Volume Management page, click Next, verify that the new volume group is listed, then click Finish.

  7. To check which physical devices are part of the volume group, open the YaST Partitioner at any time in the running system and click Volume Management › Edit › Physical Devices. Leave this screen with Abort.

    Physical Volumes in the Volume Group Named DATA
    Figure 5.2: Physical Volumes in the Volume Group Named DATA

5.3 Creating Logical Volumes

A logical volume provides a pool of space similar to what a hard disk does. To make this space usable, you need to define logical volumes. A logical volume is similar to a regular partition—you can format and mount it.

Use The YaST Partitioner to create logical volumes from an existing volume group. Assign at least one logical volume to each volume group. You can create new logical volumes as needed until all free space in the volume group has been exhausted. An LVM logical volume can optionally be thinly provisioned, allowing you to create logical volumes with sizes that overbook the available free space (see Section 5.3.1, “Thinly Provisioned Logical Volumes” for more information).

  • Normal volume:  (Default) The volume’s space is allocated immediately.

  • Thin pool:  The logical volume is a pool of space that is reserved for use with thin volumes. The thin volumes can allocate their needed space from it on demand.

  • Thin volume:  The volume is created as a sparse volume. The volume allocates needed space on demand from a thin pool.

  • Mirrored volume:  The volume is created with a defined count of mirrors.

Procedure 5.1: Setting Up a Logical Volume
  1. Launch YaST and open the Partitioner.

  2. In the left panel, select Volume Management. A list of existing Volume Groups opens in the right panel.

  3. Select the volume group in which you want to create the volume and choose Add › Logical Volume.

  4. Provide a Name for the volume and choose Normal Volume (refer to Section 5.3.1, “Thinly Provisioned Logical Volumes” for setting up thinly provisioned volumes). Proceed with Next.

  5. Specify the size of the volume and whether to use multiple stripes.

    Using a striped volume, the data will be distributed among several physical volumes. If these physical volumes reside on different hard disks, this generally results in a better reading and writing performance (like RAID 0). The maximum number of available stripes is equal to the number of physical volumes. The default (1 is to not use multiple stripes.

  6. Choose a Role for the volume. Your choice here only affects the default values for the upcoming dialog. They can be changed in the next step. If in doubt, choose Raw Volume (Unformatted).

  7. Under Formatting Options, select Format Partition, then select the File system. The content of the Options menu depends on the file system. Usually there is no need to change the defaults.

    Under Mounting Options, select Mount partition, then select the mount point. Click Fstab Options to add special mounting options for the volume.

  8. Click Finish.

  9. Click Next, verify that the changes are listed, then click Finish.

5.3.1 Thinly Provisioned Logical Volumes

An LVM logical volume can optionally be thinly provisioned. Thin provisioning allows you to create logical volumes with sizes that overbook the available free space. You create a thin pool that contains unused space reserved for use with an arbitrary number of thin volumes. A thin volume is created as a sparse volume and space is allocated from a thin pool as needed. The thin pool can be expanded dynamically when needed for cost-effective allocation of storage space. Thinly provisioned volumes also support snapshots which can be managed with Snapper—see Chapter 7, System Recovery and Snapshot Management with Snapper for more information.

To set up a thinly provisioned logical volume, proceed as described in Procedure 5.1, “Setting Up a Logical Volume”. When it comes to choosing the volume type, do not choose Normal Volume, but rather Thin Volume or Thin Pool.

Thin pool

The logical volume is a pool of space that is reserved for use with thin volumes. The thin volumes can allocate their needed space from it on demand.

Thin volume

The volume is created as a sparse volume. The volume allocates needed space on demand from a thin pool.

Important
Important: Thinly Provisioned Volumes in a Cluster

To use thinly provisioned volumes in a cluster, the thin pool and the thin volumes that use it must be managed in a single cluster resource. This allows the thin volumes and thin pool to always be mounted exclusively on the same node.

5.3.2 Creating Mirrored Volumes

A logical volume can be created with several mirrors. LVM ensures that data written to an underlying physical volume is mirrored onto a different physical volume. Thus even though a physical volume crashes, you can still access the data on the logical volume. LVM also keeps a log file to manage the synchronization process. The log contains information about which volume regions are currently undergoing synchronization with mirrors. By default the log is stored on disk and if possible on a different disk than are the mirrors. But you may specify a different location for the log, for example volatile memory.

Currently there are two types of mirror implementation available: "normal" (non-raid) mirror logical volumes and raid1 logical volumes.

After you create mirrored logical volumes, you can perform standard operations with mirrored logical volumes like activating, extending, and removing.

5.3.2.1 Setting Up Mirrored Non-raid Logical Volumes

To create a mirrored volume use the lvcreate command. The following example creates a 500 GB logical volume with two mirrors called lv1 which uses a volume group vg1.

lvcreate -L 500G -m 2 -n lv1 vg1

Such a logical volume is a linear volume (without striping) that provides three copies of the file system. The m option specifies the count of mirrors. The L option specifies the size of the logical volumes.

The logical volume is divided into regions of the 512 KB default size. If you need a different size of regions, use the -R option followed by the desired region size in megabytes. Or you can configure the preferred region size by editing the mirror_region_size option in the lvm.conf file.

5.3.2.2 Setting Up raid1 Logical Volumes

As LVM supports RAID you can implement mirroring by using RAID1. Such implementation provides the following advantages compared to the non-raid mirrors:

  • LVM maintains a fully redundant bitmap area for each mirror image, which increases its fault handling capabilities.

  • Mirror images can be temporarily split from the array and then merged back.

  • The array can handle transient failures.

  • The LVM RAID 1 implementation supports snapshots.

On the other hand, this type of mirroring implementation does not enable to create a logical volume in a clustered volume group.

To create a mirror volume by using RAID, issue the command

lvcreate --type raid1 -m 1 -L 1G -n lv1 vg1

where the options/parameters have the following meanings:

  • --type - you need to specify raid1, otherwise the command uses the implicit segment type mirror and creates a non-raid mirror.

  • -m - specifies the count of mirrors.

  • -L - specifies the size of the logical volume.

  • -n - by using this option you specify a name of the logical volume.

  • vg1 - is a name of the volume group used by the logical volume.

LVM creates a logical volume of one extent size for each data volume in the array. If you have two mirrored volumes, LVM creates another two volumes that stores metadata.

After you create a RAID logical volume, you can use the volume in the same way as a common logical volume. You can activate it, extend it, etc.

5.4 Automatically Activating Non-Root LVM Volume Groups

Activation behavior for non-root LVM volume groups is controlled in the /etc/lvm/lvm.conf file and by the auto_activation_volume_list parameter. By default, the parameter is empty and all volumes are activated. To activate only some volume groups, add the names in quotes and separate them with commas, for example:

auto_activation_volume_list = [ "vg1", "vg2/lvol1", "@tag1", "@*" ]

If you have defined a list in the auto_activation_volume_list parameter, the following will happen:

  1. Each logical volume is first checked against this list.

  2. If it does not match, the logical volume will not be activated.

By default, non-root LVM volume groups are automatically activated on system restart by Dracut. This parameter allows you to activate all volume groups on system restart, or to activate only specified non-root LVM volume groups.

5.5 Resizing an Existing Volume Group

The space provided by a volume group can be expanded at any time in the running system without service interruption by adding more physical volumes. This will allow you to add logical volumes to the group or to expand the size of existing volumes as described in Section 5.6, “Resizing a Logical Volume”.

It is also possible to reduce the size of the volume group by removing physical volumes. YaST only allows to remove physical volumes that are currently unused. To find out which physical volumes are currently in use, run the following command. The partitions (physical volumes) listed in the PE Ranges column are the ones in use:

tux > sudo pvs -o vg_name,lv_name,pv_name,seg_pe_ranges
root's password:
  VG   LV    PV         PE Ranges
             /dev/sda1
  DATA DEVEL /dev/sda5  /dev/sda5:0-3839
  DATA       /dev/sda5
  DATA LOCAL /dev/sda6  /dev/sda6:0-2559
  DATA       /dev/sda7
  DATA       /dev/sdb1
  DATA       /dev/sdc1
  1. Launch YaST and open the Partitioner.

  2. In the left panel, select Volume Management. A list of existing Volume Groups opens in the right panel.

  3. Select the volume group you want to change, then click Resize.

  4. Do one of the following:

    • Add:  Expand the size of the volume group by moving one or more physical volumes (LVM partitions) from the Available Physical Volumes list to the Selected Physical Volumes list.

    • Remove:  Reduce the size of the volume group by moving one or more physical volumes (LVM partitions) from the Selected Physical Volumes list to the Available Physical Volumes list.

  5. Click Finish.

  6. Click Next, verify that the changes are listed, then click Finish.

5.6 Resizing a Logical Volume

In case there is unused free space available in the volume group, you can enlarge a logical volume to provide more usable space. You may also reduce the size of a volume to free space in the volume group that can be used by other logical volumes.

Note
Note: Online Resizing

When reducing the size of a volume, YaST automatically resizes its file system, too. Whether a volume that is currently mounted can be resized online (that is while being mounted), depends on its file system. Growing the file system online is supported by Btrfs, XFS, Ext3, and ReiserFS.

Shrinking the file system online is only supported by Btrfs. To shrink XFS, Ext2/3/4, and ReiserFS volumes, you need to unmount them. Shrinking volumes formatted with XFS is not possible, since XFS does not support file system shrinking.

  1. Launch YaST and open the Partitioner.

  2. In the left panel, select Volume Management. A list of existing Volume Groups opens in the right panel.

  3. Select the logical volume you want to change, then click Resize.

  4. Set the intended size by using one of the following options:

    • Maximum Size.  Expand the size of the logical volume to use all space left in the volume group.

    • Minimum Size.  Reduce the size of the logical volume to the size occupied by the data and the file system metadata.

    • Custom Size.  Specify the new size for the volume. The value must be within the range of the minimum and maximum values listed above. Use K, M, G, T for Kilobytes, Megabytes, Gigabytes and Terabytes (for example 20G).

  5. Click OK.

  6. Click Next, verify that the change is listed, then click Finish.

5.7 Deleting a Volume Group or a Logical Volume

Warning
Warning: Data Loss

Deleting a volume group destroys all of the data in each of its member partitions. Deleting a logical volume destroys all data stored on the volume.

  1. Launch YaST and open the Partitioner.

  2. In the left panel, select Volume Management. A list of existing volume groups opens in the right panel.

  3. Select the volume group or the logical volume you want to remove and click Delete.

  4. Depending on your choice warning dialogs are shown. Confirm them with Yes.

  5. Click Next, verify that the deleted volume group is listed (deletion is indicated by a red colored font), then click Finish.

5.8 Using LVM Commands

For information about using LVM commands, see the man pages for the commands described in the following table. All commands need to be executed with root privileges. Either use sudo COMMAND (recommended) or execute them directly as root.

LVM Commands
pvcreate DEVICE

Initializes a device (such as /dev/sdb1) for use by LVLM as a physical volume. If there is any file system on the specified device, a warning appears. Bear in mind that pvcreate checks for existing file systems only if blkid is installed (which is done by default). If blkid is not available, pvcreate will not produce any warning and you may lose your file system without any warning.

pvdisplay DEVICE

Displays information about the LVM physical volume, such as whether it is currently being used in a logical volume.

vgcreate -c y VG_NAME DEV1 [DEV2...]

Creates a clustered volume group with one or more specified devices.

vgcreate --activationmode ACTIVATION_MODE VG_NAME

Configures the mode of volume group activation. You can specify one of the following values:

  • complete - only the logical volumes that are not affected by missing physical volumes can be activated, even though the particular logical volume can tolerate such a failure.

  • degraded - is the default activation mode. If there is a sufficient level of redundancy to activate a logical volume, the logical volume can be activated even though some physical volumes are missing.

  • partial - the LVM tries to activate the volume group even though some physical volumes are missing. If a non-redundant logical volume is missing important physical volumes, then the logical volume usually cannot be activated and is handled as an error target.

vgchange -a [ey|n] VG_NAME

Activates (-a ey) or deactivates (-a n) a volume group and its logical volumes for input/output.

When activating a volume in a cluster, ensure that you use the ey option. This option is used by default in the load script.

vgremove VG_NAME

Removes a volume group. Before using this command, remove the logical volumes, then deactivate the volume group.

vgdisplay VG_NAME

Displays information about a specified volume group.

To find the total physical extent of a volume group, enter

vgdisplay VG_NAME | grep "Total PE"
lvcreate -L SIZE -n LV_NAME VG_NAME

Creates a logical volume of the specified size.

lvcreate -L SIZE --thinpool POOL_NAME VG_NAME

Creates a thin pool named myPool of the specified size from the volume group VG_NAME.

The following example creates a thin pool with a size of 5 GB from the volume group LOCAL:

lvcreate -L 5G --thinpool myPool LOCAL
lvcreate -T VG_NAME/POOL_NAME -V SIZE -n LV_NAME

Creates a thin logical volume within the pool POOL_NAME. The following example creates a 1GB thin volume named myThin1 from the pool myPool on the volume group LOCAL:

lvcreate -T LOCAL/myPool -V 1G -n myThin1
lvcreate -T VG_NAME/POOL_NAME -V SIZE -L SIZE -n LV_NAME

It is also possible to combine thin pool and thin logical volume creation in one command:

lvcreate -T LOCAL/myPool -V 1G -L 5G -n myThin1
lvcreate --activationmode ACTIVATION_MODE LV_NAME

Configures the mode of logical volume activation. You can specify one of the following values:

  • complete - the logical volume can be activated only if all its physical volumes are active.

  • degraded - is the default activation mode. If there is a sufficient level of redundancy to activate a logical volume, the logical volume can be activated even though some physical volumes are missing.

  • partial - the LVM tries to activate the volume even though some physical volumes are missing. In this case part of the logical volume may be unavailable and it might cause data loss. This option is typically not used, but might be useful when restoring data.

You can specify the activation mode also in /etc/lvm/lvm.conf by specifying one of the above described values of the activation_mode configuration option.

lvcreate -s [-L SIZE] -n SNAP_VOLUME SOURCE_VOLUME_PATH VG_NAME

Creates a snapshot volume for the specified logical volume. If the size option (-L or --size) is not included, the snapshot is created as a thin snapshot.

lvremove /dev/VG_NAME/LV_NAME

Removes a logical volume.

Before using this command, close the logical volume by unmounting it with the umount command.

lvremove SNAP_VOLUME_PATH

Removes a snapshot volume.

lvconvert --merge SNAP_VOLUME_PATH

Reverts the logical volume to the version of the snapshot.

vgextend VG_NAME DEVICE

Adds the specified device (physical volume) to an existing volume group.

vgreduce VG_NAME DEVICE

Removes a specified physical volume from an existing volume group.

Ensure that the physical volume is not currently being used by a logical volume. If it is, you must move the data to another physical volume by using the pvmove command.

lvextend -L SIZE /dev/VG_NAME/LV_NAME

Extends the size of a specified logical volume. Afterward, you must also expand the file system to take advantage of the newly available space. See Chapter 2, Resizing File Systems for details.

lvreduce -L SIZE /dev/VG_NAME/LV_NAME

Reduces the size of a specified logical volume.

Ensure that you reduce the size of the file system first before shrinking the volume, otherwise you risk losing data. See Chapter 2, Resizing File Systems for details.

lvrename /dev/VG_NAME/LV_NAME /dev/VG_NAME/NEW_LV_NAME

Renames an existing LVM logical volume. It does not change the volume group name.

Tip
Tip: Bypassing udev on Volume Creation

In case you want to manage LV device nodes and symbolic links by using LVM instead of by using udev rules, you can achieve this by disabling notifications from udev with one of the following methods:

  • Configure activation/udev_rules = 0 and activation/udev_sync = 0 in /etc/lvm/lvm.conf.

    Note that specifying --nodevsync with the lvcreate command has the same effect as activation/udev_sync = 0; setting activation/udev_rules = 0 is still required.

  • Setting the environment variable DM_DISABLE_UDEV:

    export DM_DISABLE_UDEV=1

    This will also disable notifications from udev. In addition, all udev related settings from /etc/lvm/lvm.conf will be ignored.

5.8.1 Resizing a Logical Volume with Commands

The lvresize, lvextend, and lvreduce commands are used to resize logical volumes. See the man pages for each of these commands for syntax and options information. To extend an LV there must be enough unallocated space available on the VG.

The recommended way to grow or shrink a logical volume is to use the YaST Partitioner. When using YaST, the size of the file system in the volume will automatically be adjusted, too.

LVs can be extended or shrunk manually while they are being used, but this may not be true for a file system on them. Extending or shrinking the LV does not automatically modify the size of file systems in the volume. You must use a different command to grow the file system afterward. For information about resizing file systems, see Chapter 2, Resizing File Systems.

Ensure that you use the right sequence when manually resizing an LV:

  • If you extend an LV, you must extend the LV before you attempt to grow the file system.

  • If you shrink an LV, you must shrink the file system before you attempt to shrink the LV.

To extend the size of a logical volume:

  1. Open a terminal console.

  2. If the logical volume contains an Ext2 or Ext4 file system, which do not support online growing, dismount it. In case it contains file systems that are hosted for a virtual machine (such as a Xen VM), shut down the VM first.

  3. At the terminal console prompt, enter the following command to grow the size of the logical volume:

    sudo lvextend -L +SIZE /dev/VG_NAME/LV_NAME

    For SIZE, specify the amount of space you want to add to the logical volume, such as 10 GB. Replace /dev/VG_NAME/LV_NAME with the Linux path to the logical volume, such as /dev/LOCAL/DATA. For example:

    sudo lvextend -L +10GB /dev/vg1/v1
  4. Adjust the size of the file system. See Chapter 2, Resizing File Systems for details.

  5. In case you have dismounted the file system, mount it again.

For example, to extend an LV with a (mounted and active) Btrfs on it by 10 GB:

sudo lvextend −L +10G /dev/LOCAL/DATA
sudo btrfs filesystem resize +10G /dev/LOCAL/DATA

To shrink the size of a logical volume:

  1. Open a terminal console.

  2. If the logical volume does not contain a Btrfs file system, dismount it. In case it contains file systems that are hosted for a virtual machine (such as a Xen VM), shut down the VM first. Note that volumes with the XFS file system cannot be reduced in size.

  3. Adjust the size of the file system. See Chapter 2, Resizing File Systems for details.

  4. At the terminal console prompt, enter the following command to shrink the size of the logical volume to the size of the file system:

    sudo lvreduce /dev/VG_NAME/LV_NAME
  5. In case you have unmounted the file system, mount it again.

For example, to shrink an LV with a Btrfs on it by 5 GB:

sudo btrfs filesystem resize -size 5G /dev/LOCAL/DATA
sudo lvreduce /dev/LOCAL/DATA
Tip
Tip: Resizing the Volume and the File System with a Single Command

Starting with SUSE Linux Enterprise Server 12 SP1, lvextend, lvresize, and lvreduce support the option --resizefs which will not only change the size of the volume, but will also resize the file system. Therefore the examples for lvextend and lvreduce shown above can alternatively be run as follows:

sudo lvextend --resizefs −L +10G /dev/LOCAL/DATA
sudo lvreduce  --resizefs -L -5G /dev/LOCAL/DATA

Note that the --resizefs is supported for the following file systems: ext2/3/4, reiserfs, Btrfs, XFS. Resizing Btrfs with this option is currently only available on SUSE Linux Enterprise Server, since it is not yet accepted upstream.

5.8.2 Dynamic Aggregation of LVM Metadata via lvmetad

Most LVM commands require an accurate view of the LVM metadata stored on the disk devices in the system. With the current LVM design, if this information is not available, LVM must scan all the physical disk devices in the system. This requires a significant amount of I/O operations in systems that have many disks. In case a disk fails to respond, LVM commands might run into a timeout while waiting for the disk.

Dynamic aggregation of LVM metadata via lvmetad provides a solution for this problem. The purpose of the lvmetad daemon is to eliminate the need for this scanning by dynamically aggregating metadata information each time the status of a device changes. These events are signaled to lvmetad by udev rules. If the daemon is not running, LVM performs a scan as it normally would do.

This feature is enabled by default. In case it is disabled on your system, proceed as follows to enable it:

  1. Open a terminal console.

  2. Stop the lvmetad daemon:

    sudo systemctl stop lvm2-lvmetad
  3. Edit /etc/lvm/lvm.conf and set use_lvmetad to 1:

    use_lvmetad = 1
  4. Restart the lvmetad daemon:

    sudo systemctl start lvm2-lvmetad

5.8.3 Using LVM Cache Volumes

LVM supports the use of fast block devices (such as an SSD device) as write-back or write-through caches for large slower block devices. The cache logical volume type uses a small and fast LV to improve the performance of a large and slow LV.

To set up LVM caching, you need to create two logical volumes on the caching device. A large one is used for the caching itself, a smaller volume is used to store the caching metadata. These two volumes need to be part of the same volume group as the original volume. When these volumes are created, they need to be converted into a cache pool which needs to be attached to the original volume:

Procedure 5.2: Setting up a Cached Logical Volume
  1. Create the original volume (on a slow device) if not already existing.

  2. Add the physical volume (from a fast device) to the same volume group the original volume is part of and create the cache data volume on the physical volume.

  3. Create the cache metadata volume. The size should be 1/1000 of the size of the cache data volume, with a minimum size of 8 MB.

  4. Combine the cache data volume and metadata volume into a cache pool volume:

    lvconvert --type cache-pool --poolmetadata VOLUME_GROUP/METADATA_VOLUME VOLUME_GROUP/CACHING_VOLUME
  5. Attach the cache pool to the original volume:

    lvconvert --type cache --cachepool VOLUME_GROUP/CACHING_VOLUME VOLUME_GROUP/ORIGINAL_VOLUME

For more information on LVM caching, see the lvmcache(7) man page.

5.9 Tagging LVM2 Storage Objects

A tag is an unordered keyword or term assigned to the metadata of a storage object. Tagging allows you to classify collections of LVM storage objects in ways that you find useful by attaching an unordered list of tags to their metadata.

5.9.1 Using LVM2 Tags

After you tag the LVM2 storage objects, you can use the tags in commands to accomplish the following tasks:

  • Select LVM objects for processing according to the presence or absence of specific tags.

  • Use tags in the configuration file to control which volume groups and logical volumes are activated on a server.

  • Override settings in a global configuration file by specifying tags in the command.

A tag can be used in place of any command line LVM object reference that accepts:

  • a list of objects

  • a single object as long as the tag expands to a single object

Replacing the object name with a tag is not supported everywhere yet. After the arguments are expanded, duplicate arguments in a list are resolved by removing the duplicate arguments, and retaining the first instance of each argument.

Wherever there might be ambiguity of argument type, you must prefix a tag with the commercial at sign (@) character, such as @mytag. Elsewhere, using the @ prefix is optional.

5.9.2 Requirements for Creating LVM2 Tags

Consider the following requirements when using tags with LVM:

Supported Characters

An LVM tag word can contain the ASCII uppercase characters A to Z, lowercase characters a to z, numbers 0 to 9, underscore (_), plus (+), hyphen (-), and period (.). The word cannot begin with a hyphen. The maximum length is 128 characters.

Supported Storage Objects

You can tag LVM2 physical volumes, volume groups, logical volumes, and logical volume segments. PV tags are stored in its volume group’s metadata. Deleting a volume group also deletes the tags in the orphaned physical volume. Snapshots cannot be tagged, but their origin can be tagged.

LVM1 objects cannot be tagged because the disk format does not support it.

5.9.3 Command Line Tag Syntax

--addtagTAG_INFO

Add a tag to (or tag) an LVM2 storage object. Example:

sudo vgchange --addtag @db1 vg1
--deltagTAG_INFO

Remove a tag from (or untag) an LVM2 storage object. Example:

sudo vgchange --deltag @db1 vg1
--tagTAG_INFO

Specify the tag to use to narrow the list of volume groups or logical volumes to be activated or deactivated.

Enter the following to activate the volume if it has a tag that matches the tag provided (example):

sudo lvchange -ay --tag @db1 vg1/vol2

5.9.4 Configuration File Syntax

The following sections show example configurations for certain use cases.

5.9.4.1 Enabling Host Name Tags in the lvm.conf File

Add the following code to the /etc/lvm/lvm.conf file to enable host tags that are defined separately on host in a /etc/lvm/lvm_<HOSTNAME>.conf file.

tags {
   # Enable hostname tags
   hosttags = 1
}

You place the activation code in the /etc/lvm/lvm_<HOSTNAME>.conf file on the host. See Section 5.9.4.3, “Defining Activation”.

5.9.4.2 Defining Tags for Host Names in the lvm.conf File

tags {

   tag1 { }
      # Tag does not require a match to be set.

   tag2 {
      # If no exact match, tag is not set.
      host_list = [ "hostname1", "hostname2" ]
   }
}

5.9.4.3 Defining Activation

You can modify the /etc/lvm/lvm.conf file to activate LVM logical volumes based on tags.

In a text editor, add the following code to the file:

  activation {
      volume_list = [ "vg1/lvol0", "@database" ]
  }

Replace @database with your tag. Use "@*" to match the tag against any tag set on the host.

The activation command matches against VGNAME, VGNAME/LVNAME, or @TAG set in the metadata of volume groups and logical volumes. A volume group or logical volume is activated only if a metadata tag matches. The default if there is no match, is not to activate.

If volume_list is not present and tags are defined on the host, then it activates the volume group or logical volumes only if a host tag matches a metadata tag.

If volume_list is defined, but empty, and no tags are defined on the host, then it does not activate.

If volume_list is undefined, it imposes no limits on LV activation (all are allowed).

5.9.4.4 Defining Activation in Multiple Host Name Configuration Files

You can use the activation code in a host’s configuration file (/etc/lvm/lvm_<HOST_TAG>.conf) when host tags are enabled in the lvm.conf file. For example, a server has two configuration files in the /etc/lvm/ directory:

lvm.conf
lvm_<HOST_TAG>.conf

At start-up, load the /etc/lvm/lvm.conf file, and process any tag settings in the file. If any host tags were defined, it loads the related /etc/lvm/lvm_<HOST_TAG>.conf file. When it searches for a specific configuration file entry, it searches the host tag file first, then the lvm.conf file, and stops at the first match. Within the lvm_<HOST_TAG>.conf file, use the reverse order that tags were set in. This allows the file for the last tag set to be searched first. New tags set in the host tag file will trigger additional configuration file loads.

5.9.5 Using Tags for a Simple Activation Control in a Cluster

You can set up a simple host name activation control by enabling the hostname_tags option in the /etc/lvm/lvm.conf file. Use the same file on every machine in a cluster so that it is a global setting.

  1. In a text editor, add the following code to the /etc/lvm/lvm.conf file:

    tags {
       hostname_tags = 1
    }
  2. Replicate the file to all hosts in the cluster.

  3. From any machine in the cluster, add db1 to the list of machines that activate vg1/lvol2:

    sudo lvchange --addtag @db1 vg1/lvol2
  4. On the db1 server, enter the following to activate it:

    sudo lvchange -ay vg1/vol2

5.9.6 Using Tags to Activate On Preferred Hosts in a Cluster

The examples in this section demonstrate two methods to accomplish the following:

  • Activate volume group vg1 only on the database hosts db1 and db2.

  • Activate volume group vg2 only on the file server host fs1.

  • Activate nothing initially on the file server backup host fsb1, but be prepared for it to take over from the file server host fs1.

5.9.6.1 Option 1: Centralized Admin and Static Configuration Replicated Between Hosts

In the following solution, the single configuration file is replicated among multiple hosts.

  1. Add the @database tag to the metadata of volume group vg1. In a terminal console, enter

    sudo vgchange --addtag @database vg1
  2. Add the @fileserver tag to the metadata of volume group vg2. In a terminal console, enter

    sudo vgchange --addtag @fileserver vg2
  3. In a text editor, modify the /etc/lvm/lvm.conf file with the following code to define the @database, @fileserver, @fileserverbackup tags.

    tags {
       database {
          host_list = [ "db1", "db2" ]
       }
       fileserver {
          host_list = [ "fs1" ]
       }
       fileserverbackup {
          host_list = [ "fsb1" ]
       }
    }
    
    activation {
       # Activate only if host has a tag that matches a metadata tag
       volume_list = [ "@*" ]
    }
  4. Replicate the modified /etc/lvm/lvm.conf file to the four hosts: db1, db2, fs1, and fsb1.

  5. If the file server host goes down, vg2 can be brought up on fsb1 by entering the following commands in a terminal console on any node:

    sudo vgchange --addtag @fileserverbackup vg2
    sudo vgchange -ay vg2

5.9.6.2 Option 2: Localized Admin and Configuration

In the following solution, each host holds locally the information about which classes of volume to activate.

  1. Add the @database tag to the metadata of volume group vg1. In a terminal console, enter

    sudo vgchange --addtag @database vg1
  2. Add the @fileserver tag to the metadata of volume group vg2. In a terminal console, enter

    sudo vgchange --addtag @fileserver vg2
  3. Enable host tags in the /etc/lvm/lvm.conf file:

    1. In a text editor, modify the /etc/lvm/lvm.conf file with the following code to enable host tag configuration files.

      tags {
         hosttags = 1
      }
    2. Replicate the modified /etc/lvm/lvm.conf file to the four hosts: db1, db2, fs1, and fsb1.

  4. On host db1, create an activation configuration file for the database host db1. In a text editor, create /etc/lvm/lvm_db1.conf file and add the following code:

    activation {
       volume_list = [ "@database" ]
    }
  5. On host db2, create an activation configuration file for the database host db2. In a text editor, create /etc/lvm/lvm_db2.conf file and add the following code:

    activation {
       volume_list = [ "@database" ]
    }
  6. On host fs1, create an activation configuration file for the file server host fs1. In a text editor, create /etc/lvm/lvm_fs1.conf file and add the following code:

    activation {
       volume_list = [ "@fileserver" ]
    }
  7. If the file server host fs1 goes down, to bring up a spare file server host fsb1 as a file server:

    1. On host fsb1, create an activation configuration file for the host fsb1. In a text editor, create /etc/lvm/lvm_fsb1.conf file and add the following code:

      activation {
         volume_list = [ "@fileserver" ]
      }
    2. In a terminal console, enter one of the following commands:

      sudo vgchange -ay vg2
      sudo vgchange -ay @fileserver

6 LVM Volume Snapshots

  • Filename: storage_lvm-snapshots.xml
  • ID: cha.lvm_snapshots

A Logical Volume Manager (LVM) logical volume snapshot is a copy-on-write technology that monitors changes to an existing volume’s data blocks so that when a write is made to one of the blocks, the block’s value at the snapshot time is copied to a snapshot volume. In this way, a point-in-time copy of the data is preserved until the snapshot volume is deleted.

6.1 Understanding Volume Snapshots

A file system snapshot contains metadata about itself and data blocks from a source logical volume that has changed since the snapshot was taken. When you access data via the snapshot, you see a point-in-time copy of the source logical volume. There is no need to restore data from backup media or to overwrite the changed data.

Important
Important: Mounting Volumes with Snapshots

During the snapshot’s lifetime, the snapshot must be mounted before its source logical volume can be mounted.

LVM volume snapshots allow you to create a backup from a point-in-time view of the file system. The snapshot is created instantly and persists until you delete it. You can back up the file system from the snapshot while the volume itself continues to be available for users. The snapshot initially contains some metadata about the snapshot, but no actual data from the source logical volume. Snapshot uses copy-on-write technology to detect when data changes in an original data block. It copies the value it held when the snapshot was taken to a block in the snapshot volume, then allows the new data to be stored in the source block. As more blocks change from their original value on the source logical volume, the snapshot size grows.

When you are sizing the snapshot, consider how much data is expected to change on the source logical volume and how long you plan to keep the snapshot. The amount of space that you allocate for a snapshot volume can vary, depending on the size of the source logical volume, how long you plan to keep the snapshot, and the number of data blocks that are expected to change during the snapshot’s lifetime. The snapshot volume cannot be resized after it is created. As a guide, create a snapshot volume that is about 10% of the size of the original logical volume. If you anticipate that every block in the source logical volume will change at least one time before you delete the snapshot, then the snapshot volume should be at least as large as the source logical volume plus some additional space for metadata about the snapshot volume. Less space is required if the data changes infrequently or if the expected lifetime is sufficiently brief.

In LVM2, snapshots are read/write by default. When you write data directly to the snapshot, that block is marked in the exception table as used, and never gets copied from the source logical volume. You can mount the snapshot volume, and test application changes by writing data directly to the snapshot volume. You can easily discard the changes by dismounting the snapshot, removing the snapshot, and then remounting the source logical volume.

In a virtual guest environment, you can use the snapshot function for LVM logical volumes you create on the server’s disks, as you would on a physical server.

In a virtual host environment, you can use the snapshot function to back up the virtual machine’s storage back-end, or to test changes to a virtual machine image, such as for patches or upgrades, without modifying the source logical volume. The virtual machine must be using an LVM logical volume as its storage back-end, as opposed to using a virtual disk file. You can mount the LVM logical volume and use it to store the virtual machine image as a file-backed disk, or you can assign the LVM logical volume as a physical disk to write to it as a block device.

Beginning in SLES 11 SP3, an LVM logical volume snapshot can be thinly provisioned. Thin provisioning is assumed if you create a snapshot without a specified size. The snapshot is created as a thin volume that uses space as needed from a thin pool. A thin snapshot volume has the same characteristics as any other thin volume. You can independently activate the volume, extend the volume, rename the volume, remove the volume, and even snapshot the volume.

Important
Important: Thinly Provisioned Volumes in a Cluster

To use thinly provisioned snapshots in a cluster, the source logical volume and its snapshots must be managed in a single cluster resource. This allows the volume and its snapshots to always be mounted exclusively on the same node.

When you are done with the snapshot, it is important to remove it from the system. A snapshot eventually fills up completely as data blocks change on the source logical volume. When the snapshot is full, it is disabled, which prevents you from remounting the source logical volume.

If you create multiple snapshots for a source logical volume, remove the snapshots in a last created, first deleted order.

6.2 Creating Linux Snapshots with LVM

The Logical Volume Manager (LVM) can be used for creating snapshots of your file system.

Open a terminal console and enter

sudo lvcreate -s [-L <size>] -n SNAP_VOLUME SOURCE_VOLUME_PATH

If no size is specified, the snapshot is created as a thin snapshot.

For example:

sudo lvcreate -s -L 1G -n linux01-snap /dev/lvm/linux01

The snapshot is created as the /dev/lvm/linux01-snap volume.

6.3 Monitoring a Snapshot

Open a terminal console and enter

sudo lvdisplay SNAP_VOLUME

For example:

tux > sudo lvdisplay /dev/vg01/linux01-snap

--- Logical volume ---
  LV Name                /dev/lvm/linux01
  VG Name                vg01
  LV UUID                QHVJYh-PR3s-A4SG-s4Aa-MyWN-Ra7a-HL47KL
  LV Write Access        read/write
  LV snapshot status     active destination for /dev/lvm/linux01
  LV Status              available
  # open                 0
  LV Size                80.00 GB
  Current LE             1024
  COW-table size         8.00 GB
  COW-table LE           512
  Allocated to snapshot  30%
  Snapshot chunk size    8.00 KB
  Segments               1
  Allocation             inherit
  Read ahead sectors     0
  Block device           254:5

6.4 Deleting Linux Snapshots

Open a terminal console and enter

sudo lvremove SNAP_VOLUME_PATH

For example:

sudo lvremove /dev/lvmvg/linux01-snap

6.5 Using Snapshots for Virtual Machines on a Virtual Host

Using an LVM logical volume for a virtual machine’s back-end storage allows flexibility in administering the underlying device, such as making it easier to move storage objects, create snapshots, and back up data. You can mount the LVM logical volume and use it to store the virtual machine image as a file-backed disk, or you can assign the LVM logical volume as a physical disk to write to it as a block device. You can create a virtual disk image on the LVM logical volume, then snapshot the LVM.

You can leverage the read/write capability of the snapshot to create different instances of a virtual machine, where the changes are made to the snapshot for a particular virtual machine instance. You can create a virtual disk image on an LVM logical volume, snapshot the source logical volume, and modify the snapshot for a particular virtual machine instance. You can create another snapshot of the source logical volume, and modify it for a different virtual machine instance. The majority of the data for the different virtual machine instances resides with the image on the source logical volume.

You can also leverage the read/write capability of the snapshot to preserve the virtual disk image while testing patches or upgrades in the guest environment. You create a snapshot of the LVM volume that contains the image, and then run the virtual machine on the snapshot location. The source logical volume is unchanged, and all changes for that machine are written to the snapshot. To return to the source logical volume of the virtual machine image, you power off the virtual machine, then remove the snapshot from the source logical volume. To start over, you re-create the snapshot, mount the snapshot, and restart the virtual machine on the snapshot image.

The following procedure uses a file-backed virtual disk image and the Xen hypervisor. You can adapt the procedure in this section for other hypervisors that run on the SUSE Linux Enterprise platform, such as KVM. To run a file-backed virtual machine image from the snapshot volume:

  1. Ensure that the source logical volume that contains the file-backed virtual machine image is mounted, such as at mount point /var/lib/xen/images/<IMAGE_NAME>.

  2. Create a snapshot of the LVM logical volume with enough space to store the differences that you expect.

    sudo lvcreate -s -L 20G -n myvm-snap /dev/lvmvg/myvm

    If no size is specified, the snapshot is created as a thin snapshot.

  3. Create a mount point where you will mount the snapshot volume.

    sudo mkdir -p /mnt/xen/vm/myvm-snap
  4. Mount the snapshot volume at the mount point you created.

    sudo mount -t auto /dev/lvmvg/myvm-snap /mnt/xen/vm/myvm-snap
  5. In a text editor, copy the configuration file for the source virtual machine, modify the paths to point to the file-backed image file on the mounted snapshot volume, and save the file such as /etc/xen/myvm-snap.cfg.

  6. Start the virtual machine using the mounted snapshot volume of the virtual machine.

    sudo xm create -c /etc/xen/myvm-snap.cfg
  7. (Optional) Remove the snapshot, and use the unchanged virtual machine image on the source logical volume.

    sudo unmount /mnt/xenvms/myvm-snap
    sudo lvremove -f /dev/lvmvg/mylvm-snap
  8. (Optional) Repeat this process as desired.

6.6 Merging a Snapshot with the Source Logical Volume to Revert Changes or Roll Back to a Previous State

Snapshots can be useful if you need to roll back or restore data on a volume to a previous state. For example, you might need to revert data changes that resulted from an administrator error or a failed or undesirable package installation or upgrade.

You can use the lvconvert --merge command to revert the changes made to an LVM logical volume. The merging begins as follows:

  • If both the source logical volume and snapshot volume are not open, the merge begins immediately.

  • If the source logical volume or snapshot volume are open, the merge starts the first time either the source logical volume or snapshot volume are activated and both are closed.

  • If the source logical volume cannot be closed, such as the root file system, the merge is deferred until the next time the server reboots and the source logical volume is activated.

  • If the source logical volume contains a virtual machine image, you must shut down the virtual machine, deactivate the source logical volume and snapshot volume (by dismounting them in that order), and then issue the merge command. Because the source logical volume is automatically remounted and the snapshot volume is deleted when the merge is complete, you should not restart the virtual machine until after the merge is complete. After the merge is complete, you use the resulting logical volume for the virtual machine.

After a merge begins, the merge continues automatically after server restarts until it is complete. A new snapshot cannot be created for the source logical volume while a merge is in progress.

While the merge is in progress, reads or writes to the source logical volume are transparently redirected to the snapshot that is being merged. This allows users to immediately view and access the data as it was when the snapshot was created. They do not need to wait for the merge to complete.

When the merge is complete, the source logical volume contains the same data as it did when the snapshot was taken, plus any data changes made after the merge began. The resulting logical volume has the source logical volume’s name, minor number, and UUID. The source logical volume is automatically remounted, and the snapshot volume is removed.

  1. Open a terminal console and enter

    sudo lvconvert --merge  [-b] [-i SECONDS] [SNAP_VOLUME_PATH[...snapN]|@VOLUME_TAG]

    You can specify one or multiple snapshots on the command line. You can alternatively tag multiple source logical volumes with the same volume tag then specify @<VOLUME_TAG> on the command line. The snapshots for the tagged volumes are merged to their respective source logical volumes. For information about tagging logical volumes, see Section 5.9, “Tagging LVM2 Storage Objects”.

    The options include:

    -b, --background

    Run the daemon in the background. This allows multiple specified snapshots to be merged concurrently in parallel.

    -i, --interval <SECONDS>

    Report progress as a percentage at regular intervals. Specify the interval in seconds.

    For more information about this command, see the lvconvert(8) man page.

    For example:

    sudo lvconvert --merge /dev/lvmvg/linux01-snap

    This command merges /dev/lvmvg/linux01-snap into its source logical volume.

    sudo lvconvert --merge @mytag

    If lvol1, lvol2, and lvol3 are all tagged with mytag, each snapshot volume is merged serially with its respective source logical volume; that is: lvol1, then lvol2, then lvol3. If the --background option is specified, the snapshots for the respective tagged logical volume are merged concurrently in parallel.

  2. (Optional) If both the source logical volume and snapshot volume are open and they can be closed, you can manually deactivate and activate the source logical volume to get the merge to start immediately.

    sudo umount ORIGINAL_VOLUME
    sudo lvchange -an ORIGINAL_VOLUME
    sudo lvchange -ay ORIGINAL_VOLUME
    sudo mount ORIGINAL_VOLUME MOUNT_POINT

    For example:

    sudo umount /dev/lvmvg/lvol01
    sudo lvchange -an /dev/lvmvg/lvol01
    sudo lvchange -ay /dev/lvmvg/lvol01
    sudo mount /dev/lvmvg/lvol01 /mnt/lvol01
  3. (Optional) If both the source logical volume and snapshot volume are open and the source logical volume cannot be closed, such as the root file system, you can restart the server and mount the source logical volume to get the merge to start immediately after the restart.

Part III Software RAID

7 Software RAID Configuration

The purpose of RAID (redundant array of independent disks) is to combine several hard disk partitions into one large virtual hard disk to optimize performance, data security, or both. Most RAID controllers use the SCSI protocol because it can address a larger number of hard disks in a more effective…

8 Configuring Software RAID for the Root Partition

In SUSE Linux Enterprise Server, the Device Mapper RAID tool has been integrated into the YaST Partitioner. You can use the partitioner at install time to create a software RAID for the system device that contains your root (/) partition. The /boot partition cannot be stored on a RAID partition unle…

9 Creating Software RAID 10 Devices

This section describes how to set up nested and complex RAID 10 devices. A RAID 10 device consists of nested RAID 1 (mirroring) and RAID 0 (striping) arrays. Nested RAIDs can either be set up as striped mirrors (RAID 1+0) or as mirrored stripes (RAID 0+1). A complex RAID 10 setup also combines mirro…

10 Creating a Degraded RAID Array

A degraded array is one in which some devices are missing. Degraded arrays are supported only for RAID 1, RAID 4, RAID 5, and RAID 6. These RAID types are designed to withstand some missing devices as part of their fault-tolerance features. Typically, degraded arrays occur when a device fails. It is possible to create a degraded array on purpose.

11 Resizing Software RAID Arrays with mdadm

This section describes how to increase or reduce the size of a software RAID 1, 4, 5, or 6 device with the Multiple Device Administration (mdadm(8)) tool.

12 Storage Enclosure LED Utilities for MD Software RAIDs

Storage enclosure LED Monitoring utility (ledmon) and LED Control (ledctl) utility are Linux user space applications that use a broad range of interfaces and protocols to control storage enclosure LEDs. The primary usage is to visualize the status of Linux MD software RAID devices created with the mdadm utility. The ledmon daemon monitors the status of the drive array and updates the status of the drive LEDs. The ledctl utility allows you to set LED patterns for specified devices.

7 Software RAID Configuration

  • Filename: storage_raid.xml
  • ID: cha.raid

The purpose of RAID (redundant array of independent disks) is to combine several hard disk partitions into one large virtual hard disk to optimize performance, data security, or both. Most RAID controllers use the SCSI protocol because it can address a larger number of hard disks in a more effective way than the IDE protocol and is more suitable for parallel processing of commands. There are some RAID controllers that support IDE or SATA hard disks. Software RAID provides the advantages of RAID systems without the additional cost of hardware RAID controllers. However, this requires some CPU time and has memory requirements that make it unsuitable for real high performance computers.

Important
Important: RAID on Cluster File Systems

Software RAID underneath clustered file systems needs to be set up using a cluster multi-device (Cluster MD). Refer to the High Availability Extension documentation at https://www.suse.com/documentation/sle-ha-12/book_sleha/data/cha_ha_cluster-md.html.

SUSE Linux Enterprise offers the option of combining several hard disks into one soft RAID system. RAID implies several strategies for combining several hard disks in a RAID system, each with different goals, advantages, and characteristics. These variations are commonly known as RAID levels.

7.1 Understanding RAID Levels

This section describes common RAID levels 0, 1, 2, 3, 4, 5, and nested RAID levels.

7.1.1 RAID 0

This level improves the performance of your data access by spreading out blocks of each file across multiple disks. Actually, this is not really a RAID, because it does not provide data backup, but the name RAID 0 for this type of system has become the norm. With RAID 0, two or more hard disks are pooled together. The performance is very good, but the RAID system is destroyed and your data lost if even one hard disk fails.

7.1.2 RAID 1

This level provides adequate security for your data, because the data is copied to another hard disk 1:1. This is known as hard disk mirroring. If a disk is destroyed, a copy of its contents is available on another mirrored disk. All disks except one could be damaged without endangering your data. However, if damage is not detected, damaged data might be mirrored to the correct disk and the data is corrupted that way. The writing performance suffers a little in the copying process compared to when using single disk access (10 to 20 percent slower), but read access is significantly faster in comparison to any one of the normal physical hard disks, because the data is duplicated so can be scanned in parallel. RAID 1 generally provides nearly twice the read transaction rate of single disks and almost the same write transaction rate as single disks.

7.1.3 RAID 2 and RAID 3

These are not typical RAID implementations. Level 2 stripes data at the bit level rather than the block level. Level 3 provides byte-level striping with a dedicated parity disk and cannot service simultaneous multiple requests. Both levels are rarely used.

7.1.4 RAID 4

Level 4 provides block-level striping like Level 0 combined with a dedicated parity disk. If a data disk fails, the parity data is used to create a replacement disk. However, the parity disk might create a bottleneck for write access. Nevertheless, Level 4 is sometimes used.

7.1.5 RAID 5

RAID 5 is an optimized compromise between Level 0 and Level 1 in terms of performance and redundancy. The hard disk space equals the number of disks used minus one. The data is distributed over the hard disks as with RAID 0. Parity blocks, created on one of the partitions, are there for security reasons. They are linked to each other with XOR, enabling the contents to be reconstructed by the corresponding parity block in case of system failure. With RAID 5, no more than one hard disk can fail at the same time. If one hard disk fails, it must be replaced when possible to avoid the risk of losing data.

7.1.6 RAID 6

RAID 6 is essentially an extension of RAID 5 that allows for additional fault tolerance by using a second independent distributed parity scheme (dual parity). Even if two of the hard disks fail during the data recovery process, the system continues to be operational, with no data loss.

RAID 6 provides for extremely high data fault tolerance by sustaining multiple simultaneous drive failures. It handles the loss of any two devices without data loss. Accordingly, it requires N+2 drives to store N drives worth of data. It requires a minimum of four devices.

The performance for RAID 6 is slightly lower but comparable to RAID 5 in normal mode and single disk failure mode. It is very slow in dual disk failure mode. A RAID 6 configuration needs a considerable amount of CPU time and memory for write operations.

Table 7.1: Comparison of RAID 5 and RAID 6

Feature

RAID 5

RAID 6

Number of devices

N+1, minimum of 3

N+2, minimum of 4

Parity

Distributed, single

Distributed, dual

Performance

Medium impact on write and rebuild

More impact on sequential write than RAID 5

Fault-tolerance

Failure of one component device

Failure of two component devices

7.1.7 Nested and Complex RAID Levels

Other RAID levels have been developed, such as RAIDn, RAID 10, RAID 0+1, RAID 30, and RAID 50. Some are proprietary implementations created by hardware vendors. Examples for creating RAID 10 configurations can be found in Chapter 9, Creating Software RAID 10 Devices.

7.2 Soft RAID Configuration with YaST

The YaST soft RAID configuration can be reached from the YaST Expert Partitioner. This partitioning tool also enables you to edit and delete existing partitions and create new ones that should be used with soft RAID. These instructions apply on setting up RAID levels 0, 1, 5, and 6. Setting up RAID 10 configurations is explained in Chapter 9, Creating Software RAID 10 Devices.

  1. Launch YaST and open the Partitioner.

  2. If necessary, create partitions that should be used with your RAID configuration. Do not format them and set the partition type to 0xFD Linux RAID. When using existing partitions it is not necessary to change their partition type—YaST will automatically do so. Refer to Section 12.1, “Using the YaST Partitioner” for details.

    It is strongly recommended to use partitions stored on different hard disks to decrease the risk of losing data if one is defective (RAID 1 and 5) and to optimize the performance of RAID 0.

    For RAID 0 at least two partitions are needed. RAID 1 requires exactly two partitions, while at least three partitions are required for RAID 5. A RAID 6 setup requires at least four partitions. It is recommended to use only partitions of the same size because each segment can contribute only the same amount of space as the smallest sized partition.

  3. In the left panel, select RAID.

    A list of existing RAID configurations opens in the right panel.

  4. At the lower left of the RAID page, click Add RAID.

  5. Select a RAID Type and Add an appropriate number of partitions from the Available Devices dialog.

    You can optionally assign a RAID Name to your RAID. It will make it available as /dev/md/NAME. See Section 7.2.1, “RAID Names” for more information.

    Example RAID 5 Configuration
    Figure 7.1: Example RAID 5 Configuration

    Proceed with Next.

  6. Select the Chunk Size and, if applicable, the Parity Algorithm. The optimal chunk size depends on the type of data and the type of RAID. See https://raid.wiki.kernel.org/index.php/RAID_setup#Chunk_sizes for more information. More information on parity algorithms can be found with man 8 mdadm when searching for the --layout option. If unsure, stick with the defaults.

  7. Choose a Role for the volume. Your choice here only affects the default values for the upcoming dialog. They can be changed in the next step. If in doubt, choose Raw Volume (Unformatted).

  8. Under Formatting Options, select Format Partition, then select the File system. The content of the Options menu depends on the file system. Usually there is no need to change the defaults.

    Under Mounting Options, select Mount partition, then select the mount point. Click Fstab Options to add special mounting options for the volume.

  9. Click Finish.

  10. Click Next, verify that the changes are listed, then click Finish.

7.2.1 RAID Names

By default, software RAID devices have numeric names following the pattern mdN, where N is a number. As such they can be accessed as, for example, /dev/md127 and are listed as md127 in /proc/mdstat and /proc/partitions. Working with these names can be clumsy. SUSE Linux Enterprise Server offers two ways to work around this problem:

Providing a Named Link to the Device

You can optionally specify a name for the RAID device when creating it with YaST or on the command line with mdadm --create '/dev/md/ NAME'. The device name will still be mdN, but a link /dev/md/NAME will be created:

tux > ls -og /dev/md
total 0
lrwxrwxrwx 1 8 Dec  9 15:11 myRAID -> ../md127

The device will still be listed as md127 under /proc.

Providing a Named Device

In case a named link to the device is not sufficient for your setup, add the line CREATE names=yes to /etc/mdadm.conf by running the following command:

sudo echo "CREATE names=yes" >> /etc/mdadm.conf

It will cause names like myRAID to be used as a real device name. The device will not only be accessible at /dev/myRAID, but also be listed as myRAID under /proc. Note that this will only apply to RAIDs configured after the change to the configuration file. Active RAIDS will continue to use the mdN names until they get stopped and re-assembled.

Warning
Warning: Incompatible Tools

Not all tools may support named RAID devices. In case a tool expects a RAID device to be named mdN, it will fail to identify the devices.

7.3 Troubleshooting Software RAIDs

Check the /proc/mdstat file to find out whether a RAID partition has been damaged. If a disk fails, shut down your Linux system and replace the defective hard disk with a new one partitioned the same way. Then restart your system and enter the command mdadm /dev/mdX --add /dev/sdX. Replace X with your particular device identifiers. This integrates the hard disk automatically into the RAID system and fully reconstructs it (for all RAID levels except for RAID 0).

Although you can access all data during the rebuild, you might encounter some performance issues until the RAID has been fully rebuilt.

7.3.1 Recovery after Failing Disk is Back Again

There are several reasons a disk included in a RAID array may fail. Here is a list of the most common ones:

  • Problems with the disk media.

  • Disk drive controller failure.

  • Broken connection to the disk.

In the case of the disk media or controller failure, the device needs to be replaced or repaired. If a hot-spare was not configured within the RAID, then manual intervention is required.

In the last case, the failed device can be automatically re-added by the mdadm command after the connection is repaired (which might be automatic).

Because md/mdadm cannot reliably determine what caused the disk failure, it assumes a serious disk error and treats any failed device as faulty until it is explicitly told that the device is reliable.

Under some circumstances—such as storage devices with the internal RAID array— the connection problems are very often the cause of the device failure. In such case, you can tell mdadm that it is safe to automatically --re-add the device after it appears. You can do this by adding the following line to /etc/mdadm.conf:

POLICY action=re-add

Note that the device will be automatically re-added after re-appearing only if the udev rules cause mdadm -I DISK_DEVICE_NAME to be run on any device that spontaneously appears (default behavior), and if write-intent bitmaps are configured (they are by default).

If you want this policy to only apply to some devices and not to the others, then the path= option can be added to the POLICY line in /etc/mdadm.conf to restrict the non-default action to only selected devices. Wild cards can be used to identify groups of devices. See man 5 mdadm.conf for more information.

7.4 For More Information

Configuration instructions and more details for soft RAID can be found in the HOWTOs at:

Linux RAID mailing lists are also available, such as linux-raid at http://marc.info/?l=linux-raid.

8 Configuring Software RAID for the Root Partition

  • Filename: storage_raidroot.xml
  • ID: cha.raidroot

In SUSE Linux Enterprise Server, the Device Mapper RAID tool has been integrated into the YaST Partitioner. You can use the partitioner at install time to create a software RAID for the system device that contains your root (/) partition. The /boot partition cannot be stored on a RAID partition unless it is RAID 1.

8.1 Prerequisites for Using a Software RAID Device for the Root Partition

Ensure that your configuration meets the following requirements:

  • You need two hard disks to create the RAID 1 mirror device. The hard disks should be similarly sized. The RAID assumes the size of the smaller drive. The block storage devices can be any combination of local (in or directly attached to the machine), Fibre Channel storage subsystems, or iSCSI storage subsystems.

  • A separate partition for /boot is not required if you install the boot loader in the MBR. If installing the boot loader in the MBR is not an option, /boot needs to reside on a separate partition.

  • For UEFI machines, you need to set up a dedicated /boot/efi partition. It needs to be VFAT-formatted, and may reside on the RAID 1 device to prevent booting problems in case the physical disk with /boot/efi fails.

  • If you are using hardware RAID devices, do not attempt to run software RAIDs on top of it.

  • If you are using iSCSI target devices, you need to enable the iSCSI initiator support before you create the RAID device.

  • If your storage subsystem provides multiple I/O paths between the server and its directly attached local devices, Fibre Channel devices, or iSCSI devices that you want to use in the software RAID, you need to enable the multipath support before you create the RAID device.

8.2 Setting Up the System with a Software RAID Device for the Root (/) Partition

  1. Start the installation with YaST and proceed as described in Chapter 6, Installation with YaST until you reach the Suggested Partitioning step.

  2. Click Expert Partitioner to open the custom partitioning tool.

  3. (Optional) If there are iSCSI target devices that you want to use, you need to enable the iSCSI Initiator software by choosing Configure › Configure iSCSI from the lower right section of the screen. Refer to Chapter 14, Mass Storage over IP Networks: iSCSI for further details.

  4. (Optional) If there are multiple I/O paths to the devices that you want to use you need to enable multipath support by choosing Configure › Configure Multipath › Yes from the lower right section of the screen.

  5. (Optional) In case you have neither configured iSCSI or Multipath, the default proposal settings are shown. Click Rescan Devices to delete them.

  6. Set up the 0xFD Linux RAID format for each of the devices you want to use for the software RAID. You should use RAID for /, /boot/efi, or swap partitions.

    1. In the left panel, select Hard Disks and select the device you want to use, then click Add Partition.

    2. Under New Partition Type, select Primary Partition, then click Next.

    3. Under New Partition Size, specify the size to use, then click Next.

    4. Under Role, choose Raw Volume (unformatted).

    5. Select Do not format and set the File SystemID to 0xFD Linux RAID.

    6. Click Finish and repeat these instructions for the second partition.

  7. Create the RAID device for the / partition.

    1. In the left panel, select RAID and then Add RAID.

    2. Set the desired RAID Type for the / partition and the RAID name to system.

    3. Select the two RAID devices you prepared in the previous step from the Available Devices section and Add them.

      Proceed with Next.

    4. Under RAID Options, select the chunk size from the drop-down box. Sticking with the default is a safe choice.

    5. Under Role, select Operating System and proceed with Finish.

    6. Select the File System and set the mount point to /. Leave the dialog with Finish.

  8. The software RAID device is managed by Device Mapper, and creates a device under the /dev/md/system path.

  9. Optionally for UEFI machines, use similar steps to create the /boot/efi mounted partition. Remember that only RAID 1 is supported for /boot/efi, and the partition needs to be formatted with the FAT file system.

    /, /boot/efi, and swap on RAIDs
    Figure 8.1: /, /boot/efi, and swap on RAIDs
  10. Click Accept to leave the partitioner.

    The new proposal appears on the Suggested Partitioning page.

  11. Continue with the installation. For UEFI machines with a separate /boot/efi partition, click Booting on the Installation Settings screen and set GRUB2 for EFI as the Boot Loader. Check that the Enable Secure Boot Support option is activated.

    Whenever you reboot your server, Device Mapper is started at boot time so that the software RAID is automatically recognized, and the operating system on the root (/) partition can be started.

9 Creating Software RAID 10 Devices

  • Filename: storage_raid10.xml
  • ID: cha.raid10

This section describes how to set up nested and complex RAID 10 devices. A RAID 10 device consists of nested RAID 1 (mirroring) and RAID 0 (striping) arrays. Nested RAIDs can either be set up as striped mirrors (RAID 1+0) or as mirrored stripes (RAID 0+1). A complex RAID 10 setup also combines mirrors and stripes and additional data security by supporting a higher data redundancy level.

9.1 Creating Nested RAID 10 Devices with mdadm

A nested RAID device consists of a RAID array that uses another RAID array as its basic element, instead of using physical disks. The goal of this configuration is to improve the performance and fault tolerance of the RAID. Setting up nested RAID levels is not supported by YaST, but can be done by using the mdadm command line tool.

Based on the order of nesting, two different nested RAIDs can be set up. This document uses the following terminology:

  • RAID 1+0:  RAID 1 (mirror) arrays are built first, then combined to form a RAID 0 (stripe) array.

  • RAID 0+1:  RAID 0 (stripe) arrays are built first, then combined to form a RAID 1 (mirror) array.

The following table describes the advantages and disadvantages of RAID 10 nesting as 1+0 versus 0+1. It assumes that the storage objects you use reside on different disks, each with a dedicated I/O capability.

Table 9.1: Nested RAID Levels

RAID Level

Description

Performance and Fault Tolerance

10 (1+0)

RAID 0 (stripe) built with RAID 1 (mirror) arrays

RAID 1+0 provides high levels of I/O performance, data redundancy, and disk fault tolerance. Because each member device in the RAID 0 is mirrored individually, multiple disk failures can be tolerated and data remains available as long as the disks that fail are in different mirrors.

You can optionally configure a spare for each underlying mirrored array, or configure a spare to serve a spare group that serves all mirrors.

10 (0+1)

RAID 1 (mirror) built with RAID 0 (stripe) arrays

RAID 0+1 provides high levels of I/O performance and data redundancy, but slightly less fault tolerance than a 1+0. If multiple disks fail on one side of the mirror, then the other mirror is available. However, if disks are lost concurrently on both sides of the mirror, all data is lost.

This solution offers less disk fault tolerance than a 1+0 solution, but if you need to perform maintenance or maintain the mirror on a different site, you can take an entire side of the mirror offline and still have a fully functional storage device. Also, if you lose the connection between the two sites, either site operates independently of the other. That is not true if you stripe the mirrored segments, because the mirrors are managed at a lower level.

If a device fails, the mirror on that side fails because RAID 1 is not fault-tolerant. Create a new RAID 0 to replace the failed side, then resynchronize the mirrors.

9.1.1 Creating Nested RAID 10 (1+0) with mdadm

A nested RAID 1+0 is built by creating two or more RAID 1 (mirror) devices, then using them as component devices in a RAID 0.

Important
Important: Multipathing

If you need to manage multiple connections to the devices, you must configure multipath I/O before configuring the RAID devices. For information, see Chapter 17, Managing Multipath I/O for Devices.

The procedure in this section uses the device names shown in the following table. Ensure that you modify the device names with the names of your own devices.

Table 9.2: Scenario for Creating a RAID 10 (1+0) by Nesting

Raw Devices

RAID 1 (mirror)

RAID 1+0 (striped mirrors)

/dev/sdb1
/dev/sdc1

/dev/md0

/dev/md2

/dev/sdd1
/dev/sde1

/dev/md1

  1. Open a terminal console.

  2. If necessary, create four 0xFD Linux RAID partitions of equal size using a disk partitioner such as parted.

  3. Create two software RAID 1 devices, using two different devices for each device. At the command prompt, enter these two commands:

    sudo mdadm --create /dev/md0 --run --level=1 --raid-devices=2 /dev/sdb1 /dev/sdc1
    sudo mdadm --create /dev/md1 --run --level=1 --raid-devices=2 /dev/sdd1 /dev/sde1
  4. Create the nested RAID 1+0 device. At the command prompt, enter the following command using the software RAID 1 devices you created in the previous step:

    sudo mdadm --create /dev/md2 --run --level=0 --chunk=64 \
    --raid-devices=2 /dev/md0 /dev/md1

    The default chunk size is 64 KB.

  5. Create a file system on the RAID 1+0 device /dev/md2, for example an XFS file system:

    sudo mkfs.xfs /dev/md2

    Modify the command to use a different file system.

  6. Edit the /etc/mdadm.conf file or create it, if it does not exist (for example by running sudo vi /etc/mdadm.conf). Add the following lines (if the file already exists, the first line probably already exists).

    DEVICE containers partitions
    ARRAY /dev/md0 UUID=UUID
    ARRAY /dev/md1 UUID=UUID
    ARRAY /dev/md2 UUID=UUID

    The UUID of each device can be retrieved with the following command:

    sudo mdadm -D /dev/DEVICE | grep UUID
  7. Edit the /etc/fstab file to add an entry for the RAID 1+0 device /dev/md2. The following example shows an entry for a RAID device with the XFS file system and /data as a mount point.

    /dev/md2 /data xfs defaults 1 2
  8. Mount the RAID device:

    sudo mount /data

9.1.2 Creating Nested RAID 10 (0+1) with mdadm

A nested RAID 0+1 is built by creating two to four RAID 0 (striping) devices, then mirroring them as component devices in a RAID 1.

Important
Important: Multipathing

If you need to manage multiple connections to the devices, you must configure multipath I/O before configuring the RAID devices. For information, see Chapter 17, Managing Multipath I/O for Devices.

In this configuration, spare devices cannot be specified for the underlying RAID 0 devices because RAID 0 cannot tolerate a device loss. If a device fails on one side of the mirror, you must create a replacement RAID 0 device, than add it into the mirror.

The procedure in this section uses the device names shown in the following table. Ensure that you modify the device names with the names of your own devices.

Table 9.3: Scenario for Creating a RAID 10 (0+1) by Nesting

Raw Devices

RAID 0 (stripe)

RAID 0+1 (mirrored stripes)

/dev/sdb1
/dev/sdc1

/dev/md0

/dev/md2

/dev/sdd1
/dev/sde1

/dev/md1

  1. Open a terminal console.

  2. If necessary, create four 0xFD Linux RAID partitions of equal size using a disk partitioner such as parted.

  3. Create two software RAID 0 devices, using two different devices for each RAID 0 device. At the command prompt, enter these two commands:

    sudo mdadm --create /dev/md0 --run --level=0 --chunk=64 \
    --raid-devices=2 /dev/sdb1 /dev/sdc1
    sudo mdadm --create /dev/md1 --run --level=0 --chunk=64 \
    --raid-devices=2 /dev/sdd1 /dev/sde1

    The default chunk size is 64 KB.

  4. Create the nested RAID 0+1 device. At the command prompt, enter the following command using the software RAID 0 devices you created in the previous step:

    sudo mdadm --create /dev/md2 --run --level=1 --raid-devices=2 /dev/md0 /dev/md1
  5. Create a file system on the RAID 1+0 device /dev/md2, for example an XFS file system:

    sudo mkfs.xfs /dev/md2

    Modify the command to use a different file system.

  6. Edit the /etc/mdadm.conf file or create it, if it does not exist (for example by running sudo vi /etc/mdadm.conf). Add the following lines (if the file exists, the first line probably already exists, too).

    DEVICE containers partitions
    ARRAY /dev/md0 UUID=UUID
    ARRAY /dev/md1 UUID=UUID
    ARRAY /dev/md2 UUID=UUID

    The UUID of each device can be retrieved with the following command:

    sudo mdadm -D /dev/DEVICE | grep UUID
  7. Edit the /etc/fstab file to add an entry for the RAID 1+0 device /dev/md2. The following example shows an entry for a RAID device with the XFS file system and /data as a mount point.

    /dev/md2 /data xfs defaults 1 2
  8. Mount the RAID device:

    sudo mount /data

9.2 Creating a Complex RAID 10

YaST (and mdadm with the --level=10 option) creates a single complex software RAID 10 that combines features of both RAID 0 (striping) and RAID 1 (mirroring). Multiple copies of all data blocks are arranged on multiple drives following a striping discipline. Component devices should be the same size.

The complex RAID 10 is similar in purpose to a nested RAID 10 (1+0), but differs in the following ways:

Table 9.4: Complex RAID 10 compared to Nested RAID 10

Feature

Complex RAID 10

Nested RAID 10 (1+0)

Number of devices

Allows an even or odd number of component devices

Requires an even number of component devices

Component devices

Managed as a single RAID device

Manage as a nested RAID device

Striping

Striping occurs in the near or far layout on component devices.

The far layout provides sequential read throughput that scales by number of drives, rather than number of RAID 1 pairs.

Striping occurs consecutively across component devices

Multiple copies of data

Two or more copies, up to the number of devices in the array

Copies on each mirrored segment

Hot spare devices

A single spare can service all component devices

Configure a spare for each underlying mirrored array, or configure a spare to serve a spare group that serves all mirrors.

9.2.1 Number of Devices and Replicas in the Complex RAID 10

When configuring a complex RAID 10 array, you must specify the number of replicas of each data block that are required. The default number of replicas is two, but the value can be two to the number of devices in the array.

You must use at least as many component devices as the number of replicas you specify. However, the number of component devices in a RAID 10 array does not need to be a multiple of the number of replicas of each data block. The effective storage size is the number of devices divided by the number of replicas.

For example, if you specify two replicas for an array created with five component devices, a copy of each block is stored on two different devices. The effective storage size for one copy of all data is 5/2 or 2.5 times the size of a component device.

9.2.2 Layout

The complex RAID 10 setup supports three different layouts which define how the data blocks are arranged on the disks. The available layouts are near (default), far and offset. They have different performance characteristics, so it is important to choose the right layout for your workload.

9.2.2.1 Near Layout

With the near layout, copies of a block of data are striped near each other on different component devices. That is, multiple copies of one data block are at similar offsets in different devices. Near is the default layout for RAID 10. For example, if you use an odd number of component devices and two copies of data, some copies are perhaps one chunk further into the device.

The near layout for the complex RAID 10 yields read and write performance similar to RAID 0 over half the number of drives.

Near layout with an even number of disks and two replicas:

sda1 sdb1 sdc1 sde1
  0    0    1    1
  2    2    3    3
  4    4    5    5
  6    6    7    7
  8    8    9    9

Near layout with an odd number of disks and two replicas:

sda1 sdb1 sdc1 sde1 sdf1
  0    0    1    1    2
  2    3    3    4    4
  5    5    6    6    7
  7    8    8    9    9
  10   10   11   11   12

9.2.2.2 Far Layout

The far layout stripes data over the early part of all drives, then stripes a second copy of the data over the later part of all drives, making sure that all copies of a block are on different drives. The second set of values starts halfway through the component drives.

With a far layout, the read performance of the complex RAID 10 is similar to a RAID 0 over the full number of drives, but write performance is substantially slower than a RAID 0 because there is more seeking of the drive heads. It is best used for read-intensive operations such as for read-only file servers.

The speed of the RAID 10 for writing is similar to other mirrored RAID types, like RAID 1 and RAID 10 using near layout, as the elevator of the file system schedules the writes in a more optimal way than raw writing. Using RAID 10 in the far layout is well suited for mirrored writing applications.

Far layout with an even number of disks and two replicas:

sda1 sdb1 sdc1 sde1
  0    1    2    3
  4    5    6    7
  . . .
  3    0    1    2
  7    4    5    6

Far layout with an odd number of disks and two replicas:

sda1 sdb1 sdc1 sde1 sdf1
  0    1    2    3    4
  5    6    7    8    9
  . . .
  4    0    1    2    3
  9    5    6    7    8

9.2.2.3 Offset Layout

The offset layout duplicates stripes so that the multiple copies of a given chunk are laid out on consecutive drives and at consecutive offsets. Effectively, each stripe is duplicated and the copies are offset by one device. This should give similar read characteristics to a far layout if a suitably large chunk size is used, but without as much seeking for writes.

Offset layout with an even number of disks and two replicas:

sda1 sdb1 sdc1 sde1
  0    1    2    3
  3    0    1    2
  4    5    6    7
  7    4    5    6
  8    9   10   11
 11    8    9   10

Offset layout with an odd number of disks and two replicas:

sda1 sdb1 sdc1 sde1 sdf1
  0    1    2    3    4
  4    0    1    2    3
  5    6    7    8    9
  9    5    6    7    8
 10   11   12   13   14
 14   10   11   12   13

9.2.2.4 Specifying the number of Replicas and the Layout with YaST and mdadm

The number of replicas and the layout is specified as Parity Algorithm in YaST or with the --layout parameter for mdadm. The following values are accepted:

nN

Specify n for near layout and replace N with the number of replicas. n2 is the default that is used when not configuring layout and the number of replicas.

fN

Specify f for far layout and replace N with the number of replicas.

oN

Specify o for offset layout and replace N with the number of replicas.

Note
Note: Number of Replicas

YaST automatically offers a selection of all possible values for the Parity Algorithm parameter.

9.2.3 Creating a Complex RAID 10 with the YaST Partitioner

  1. Launch YaST and open the Partitioner.

  2. If necessary, create partitions that should be used with your RAID configuration. Do not format them and set the partition type to 0xFD Linux RAID. When using existing partitions it is not necessary to change their partition type—YaST will automatically do so. Refer to Section 12.1, “Using the YaST Partitioner” for details.

    For RAID 10 at least four partitions are needed. It is strongly recommended to use partitions stored on different hard disks to decrease the risk of losing data if one is defective. It is recommended to use only partitions of the same size because each segment can contribute only the same amount of space as the smallest sized partition.

  3. In the left panel, select RAID.

    A list of existing RAID configurations opens in the right panel.

  4. At the lower left of the RAID page, click Add RAID.

  5. Under RAID Type, select RAID 10 (Mirroring and Striping).

    You can optionally assign a RAID Name to your RAID. It will make it available as /dev/md/NAME. See Section 7.2.1, “RAID Names” for more information.

  6. In the Available Devices list, select the desired partitions, then click Add to move them to the Selected Devices list.

  7. (Optional) Click Classify to specify the preferred order of the disks in the RAID array.

    For RAID types such as RAID 10, where the order of added disks matters, you can specify the order in which the devices will be used. This will ensure that one half of the array resides on one disk subsystem and the other half of the array resides on a different disk subsystem. For example, if one disk subsystem fails, the system keeps running from the second disk subsystem.

    1. Select each disk in turn and click one of the Class X buttons, where X is the letter you want to assign to the disk. Available classes are A, B, C, D and E but for many cases fewer classes are needed (only A and B, for example). Assign all available RAID disks this way.

      You can press the Ctrl or Shift key to select multiple devices. You can also right-click a selected device and choose the appropriate class from the context menu.

    2. Specify the order of the devices by selecting one of the sorting options:

      Sorted Sorts all devices of class A before all devices of class B and so on. For example: AABBCC.

      Interleaved Sorts devices by the first device of class A, then first device of class B, then all the following classes with assigned devices. Then the second device of class A, the second device of class B, and so on follows. All devices without a class are sorted to the end of the devices list. For example: ABCABC.

      Pattern File:  Select an existing file that contains multiple lines, where each is a regular expression and a class name ("sda.* A"). All devices that match the regular expression are assigned to the specified class for that line. The regular expression is matched against the kernel name (/dev/sda1), the udev path name (/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0-part1) and then the udev ID (dev/disk/by-id/ata-ST3500418AS_9VMN8X8L-part1). The first match made determines the class if a device’s name matches more than one regular expression.

    3. At the bottom of the dialog, click OK to confirm the order.

  8. Click Next.

  9. Under RAID Options, specify the Chunk Size and Parity Algorithm, then click Next.

    For a RAID 10, the parity options are n (near), f (far), and o (offset). The number indicates the number of replicas of each data block that are required. Two is the default. For information, see Section 9.2.2, “Layout”.

  10. Add a file system and mount options to the RAID device, then click Finish.

  11. Click Next.

  12. Verify the changes to be made, then click Finish to create the RAID.

9.2.4 Creating a Complex RAID 10 with mdadm

The procedure in this section uses the device names shown in the following table. Ensure that you modify the device names with the names of your own devices.

Table 9.5: Scenario for Creating a RAID 10 Using mdadm

Raw Devices

RAID 10

/dev/sdf1

/dev/sdg1

/dev/sdh1

/dev/sdi1

/dev/md3

  1. Open a terminal console.

  2. If necessary, create at least four 0xFD Linux RAID partitions of equal size using a disk partitioner such as parted.

  3. Create a RAID 10 by entering the following command.

    mdadm --create /dev/md3 --run --level=10 --chunk=32 --raid-devices=4 \
    /dev/sdf1 /dev/sdg1 /dev/sdh1 /dev/sdi1

    Make sure to adjust the value for --raid-devices and the list of partitions according to your setup.

    The command creates an array with near layout and two replicas. To change any of the two values, use the --layout as described in Section 9.2.2.4, “Specifying the number of Replicas and the Layout with YaST and mdadm”.

  4. Create a file system on the RAID 10 device /dev/md3, for example an XFS file system:

    sudo mkfs.xfs /dev/md3

    Modify the command to use a different file system.

  5. Edit the /etc/mdadm.conf file or create it, if it does not exist (for example by running sudo vi /etc/mdadm.conf). Add the following lines (if the file exists, the first line probably already exists, too) .

    DEVICE containers partitions
    ARRAY /dev/md3 UUID=UUID

    The UUID of the device can be retrieved with the following command:

    sudo mdadm -D /dev/md3 | grep UUID
  6. Edit the /etc/fstab file to add an entry for the RAID 10 device /dev/md3. The following example shows an entry for a RAID device with the XFS file system and /data as a mount point.

    /dev/md3 /data xfs defaults 1 2
  7. Mount the RAID device:

    sudo mount /data

10 Creating a Degraded RAID Array

  • Filename: storage_degraded_raid.xml
  • ID: cha.raid_degraded
Abstract

A degraded array is one in which some devices are missing. Degraded arrays are supported only for RAID 1, RAID 4, RAID 5, and RAID 6. These RAID types are designed to withstand some missing devices as part of their fault-tolerance features. Typically, degraded arrays occur when a device fails. It is possible to create a degraded array on purpose.

RAID Type

Allowable Number of Slots Missing

 

RAID 1

All but one device

 

RAID 4

One slot

 

RAID 5

One slot

 

RAID 6

One or two slots

 

To create a degraded array in which some devices are missing, simply give the word missing in place of a device name. This causes mdadm to leave the corresponding slot in the array empty.

When creating a RAID 5 array, mdadm automatically creates a degraded array with an extra spare drive. This is because building the spare into a degraded array is generally faster than resynchronizing the parity on a non-degraded, but not clean, array. You can override this feature with the --force option.

Creating a degraded array might be useful if you want create a RAID, but one of the devices you want to use already has data on it. In that case, you create a degraded array with other devices, copy data from the in-use device to the RAID that is running in degraded mode, add the device into the RAID, then wait while the RAID is rebuilt so that the data is now across all devices. An example of this process is given in the following procedure:

  1. To create a degraded RAID 1 device /dev/md0, using one single drive /dev/sd1, enter the following at the command prompt:

    mdadm --create /dev/md0 -l 1 -n 2 /dev/sda1 missing

    The device should be the same size or larger than the device you plan to add to it.

  2. If the device you want to add to the mirror contains data that you want to move to the RAID array, copy it now to the RAID array while it is running in degraded mode.

  3. Add the device you copied the data from to the mirror. For example, to add /dev/sdb1 to the RAID, enter the following at the command prompt:

    mdadm /dev/md0 -a /dev/sdb1

    You can add only one device at a time. You must wait for the kernel to build the mirror and bring it fully online before you add another mirror.

  4. Monitor the build progress by entering the following at the command prompt:

    cat /proc/mdstat

    To see the rebuild progress while being refreshed every second, enter

    watch -n 1 cat /proc/mdstat

11 Resizing Software RAID Arrays with mdadm

  • Filename: storage_mdadm-resize.xml
  • ID: cha.raid_resize
Abstract

This section describes how to increase or reduce the size of a software RAID 1, 4, 5, or 6 device with the Multiple Device Administration (mdadm(8)) tool.

Resizing an existing software RAID device involves increasing or decreasing the space contributed by each component partition. The file system that resides on the RAID must also be able to be resized to take advantage of the changes in available space on the device. In SUSE Linux Enterprise Server, file system resizing utilities are available for file systems Btrfs, Ext2, Ext3, Ext4, ReiserFS, and XFS (increase size only). Refer to Chapter 2, Resizing File Systems for more information.

The mdadm tool supports resizing only for software RAID levels 1, 4, 5, and 6. These RAID levels provide disk fault tolerance so that one component partition can be removed at a time for resizing. In principle, it is possible to perform a hot resize for RAID partitions, but you must take extra care for your data when doing so.

Warning
Warning: Back Up your Data Before Resizing

Resizing any partition or file system involves some risks that can potentially result in losing data. To avoid data loss, ensure that you back up your data before you begin any resizing task.

Resizing the RAID involves the following tasks. The order in which these tasks are performed depends on whether you are increasing or decreasing its size.

Table 11.1: Tasks Involved in Resizing a RAID

Tasks

Description

Order If Increasing Size

Order If Decreasing Size

Resize each of the component partitions.

Increase or decrease the active size of each component partition. You remove only one component partition at a time, modify its size, then return it to the RAID.

1

2

Resize the software RAID itself.

The RAID does not automatically know about the increases or decreases you make to the underlying component partitions. You must inform it about the new size.

2

3

Resize the file system.

You must resize the file system that resides on the RAID. This is possible only for file systems that provide tools for resizing.

3

1

The procedures in the following sections use the device names shown in the following table. Ensure that you modify the names to use the names of your own devices.

Table 11.2: Scenario for Increasing the Size of Component Partitions

RAID Device

Component Partitions

/dev/md0

/dev/sda1

/dev/sdb1

/dev/sdc1

11.1 Increasing the Size of a Software RAID

Increasing the size of a software RAID involves the following tasks in the given order: increase the size of all partitions the RAID consists of, increase the size of the RAID itself and, finally, increase the size of the file system.

Warning
Warning: Potential Data Loss

If a RAID does not have disk fault tolerance, or it is simply not consistent, data loss results if you remove any of its partitions. Be very careful when removing partitions, and ensure that you have a backup of your data available.

11.1.1 Increasing the Size of Component Partitions

Apply the procedure in this section to increase the size of a RAID 1, 4, 5, or 6. For each component partition in the RAID, remove the partition from the RAID, modify its size, return it to the RAID, then wait until the RAID stabilizes to continue. While a partition is removed, the RAID operates in degraded mode and has no or reduced disk fault tolerance. Even for RAIDs that can tolerate multiple concurrent disk failures, do not remove more than one component partition at a time. To increase the size of the component partitions for the RAID, proceed as follows:

  1. Open a terminal console.

  2. Ensure that the RAID array is consistent and synchronized by entering

    cat /proc/mdstat

    If your RAID array is still synchronizing according to the output of this command, you must wait until synchronization is complete before continuing.

  3. Remove one of the component partitions from the RAID array. For example, to remove /dev/sda1, enter

    sudo mdadm /dev/md0 --fail /dev/sda1 --remove /dev/sda1

    To succeed, both the fail and remove actions must be specified.

  4. Increase the size of the partition that you removed in the previous step by doing one of the following:

    • Increase the size of the partition, using a disk partitioner such as the YaST Partitioner or the command line tool parted. This option is the usual choice.

    • Replace the disk on which the partition resides with a higher-capacity device. This option is possible only if no other file systems on the original disk are accessed by the system. When the replacement device is added back into the RAID, it takes much longer to synchronize the data because all of the data that was on the original device must be rebuilt.

  5. Re-add the partition to the RAID array. For example, to add /dev/sda1, enter

    sudo mdadm -a /dev/md0 /dev/sda1

    Wait until the RAID is synchronized and consistent before continuing with the next partition.

  6. Repeat these steps for each of the remaining component devices in the array. Ensure that you modify the commands for the correct component partition.

  7. If you get a message that tells you that the kernel could not re-read the partition table for the RAID, you must reboot the computer after all partitions have been resized to force an update of the partition table.

  8. Continue with Section 11.1.2, “Increasing the Size of the RAID Array”.

11.1.2 Increasing the Size of the RAID Array

After you have resized each of the component partitions in the RAID (see Section 11.1.1, “Increasing the Size of Component Partitions”), the RAID array configuration continues to use the original array size until you force it to be aware of the newly available space. You can specify a size for the RAID or use the maximum available space.

The procedure in this section uses the device name /dev/md0 for the RAID device. Ensure that you modify the name to use the name of your own device.

  1. Open a terminal console.

  2. Ensure that the RAID array is consistent and synchronized by entering

    cat /proc/mdstat

    If your RAID array is still synchronizing according to the output of this command, you must wait until synchronization is complete before continuing.

  3. Check the size of the array and the device size known to the array by entering

    sudo mdadm -D /dev/md0 | grep -e "Array Size" -e "Dev Size"
  4. Do one of the following:

    • Increase the size of the array to the maximum available size by entering

      sudo mdadm --grow /dev/md0 -z max
    • Increase the size of the array to the maximum available size by entering

      sudo mdadm --grow /dev/md0 -z max --assume-clean

      The array uses any space that has been added to the devices, but this space will not be synchronized. This is recommended for RAID 1 because the synchronization is not needed. It can be useful for other RAID levels if the space that was added to the member devices was pre-zeroed.

    • Increase the size of the array to a specified value by entering

      sudo mdadm --grow /dev/md0 -z SIZE

      Replace SIZE with an integer value in kilobytes (a kilobyte is 1024 bytes) for the desired size.

  5. Recheck the size of your array and the device size known to the array by entering

    sudo mdadm -D /dev/md0 | grep -e "Array Size" -e "Dev Size"
  6. Do one of the following:

11.1.3 Increasing the Size of the File System

After you increase the size of the array (see Section 11.1.2, “Increasing the Size of the RAID Array”), you are ready to resize the file system.

You can increase the size of the file system to the maximum space available or specify an exact size. When specifying an exact size for the file system, ensure that the new size satisfies the following conditions:

  • The new size must be greater than the size of the existing data; otherwise, data loss occurs.

  • The new size must be equal to or less than the current RAID size because the file system size cannot extend beyond the space available.

Refer to Chapter 2, Resizing File Systems for detailed instructions.

11.2 Decreasing the Size of a Software RAID

Decreasing the Size of a Software RAID involves the following tasks in the given order: decrease the size of the file system, decrease the size of all partitions the RAID consists of, and finally decrease the size of the RAID itself.

Warning
Warning: Potential Data Loss

If a RAID does not have disk fault tolerance, or it is simply not consistent, data loss results if you remove any of its partitions. Be very careful when removing partitions, and ensure that you have a backup of your data available.

Important
Important: XFS

Decreasing the size of a file system formatted with XFS is not possible, since such a feature is not supported by XFS. As a consequence, the size of a RAID that uses the XFS file system cannot be decreased.

11.2.1 Decreasing the Size of the File System

When decreasing the size of the file system on a RAID device, ensure that the new size satisfies the following conditions:

  • The new size must be greater than the size of the existing data; otherwise, data loss occurs.

  • The new size must be equal to or less than the current RAID size because the file system size cannot extend beyond the space available.

Refer to Chapter 2, Resizing File Systems for detailed instructions.

11.2.2 Decreasing the Size of the RAID Array

After you have resized the file system (see Section 11.2.1, “Decreasing the Size of the File System”), the RAID array configuration continues to use the original array size until you force it to reduce the available space. Use the mdadm --grow mode to force the RAID to use a smaller segment size. To do this, you must use the -z option to specify the amount of space in kilobytes to use from each device in the RAID. This size must be a multiple of the chunk size, and it must leave about 128 KB of space for the RAID superblock to be written to the device.

The procedure in this section uses the device name /dev/md0 for the RAID device. Ensure that you modify commands to use the name of your own device.

  1. Open a terminal console.

  2. Check the size of the array and the device size known to the array by entering

    sudo mdadm -D /dev/md0 | grep -e "Array Size" -e "Dev Size"
  3. Decrease the array’s device size to a specified value by entering

    sudo mdadm --grow /dev/md0 -z SIZE

    Replace SIZE with an integer value in kilobytes for the desired size. (A kilobyte is 1024 bytes.)

    For example, the following command sets the segment size for each RAID device to about 40 GB where the chunk size is 64 KB. It includes 128 KB for the RAID superblock.

    sudo mdadm --grow /dev/md2 -z 41943168
  4. Recheck the size of your array and the device size known to the array by entering

    sudo mdadm -D /dev/md0 | grep -e "Array Size" -e "Device Size"
  5. Do one of the following:

11.2.3 Decreasing the Size of Component Partitions

After you decrease the segment size that is used on each device in the RAID (see Section 11.2.2, “Decreasing the Size of the RAID Array”), the remaining space in each component partition is not used by the RAID. You can leave partitions at their current size to allow for the RAID to grow at a future time, or you can reclaim this now unused space.

To reclaim the space, you decrease the component partitions one at a time. For each component partition, you remove it from the RAID, reduce its partition size, return the partition to the RAID, then wait until the RAID stabilizes. To allow for metadata, you should specify a slightly larger size than the size you specified for the RAID in Section 11.2.2, “Decreasing the Size of the RAID Array”.

While a partition is removed, the RAID operates in degraded mode and has no or reduced disk fault tolerance. Even for RAIDs that can tolerate multiple concurrent disk failures, you should never remove more than one component partition at a time. To decrease the size of the component partitions for the RAID, proceed as follows:

  1. Open a terminal console.

  2. Ensure that the RAID array is consistent and synchronized by entering

    cat /proc/mdstat

    If your RAID array is still synchronizing according to the output of this command, you must wait until synchronization is complete before continuing.

  3. Remove one of the component partitions from the RAID array. For example, to remove /dev/sda1, enter

    sudo mdadm /dev/md0 --fail /dev/sda1 --remove /dev/sda1

    To succeed, both the fail and remove actions must be specified.

  4. Decrease the size of the partition that you removed in the previous step to a size that is slightly larger than the size you set for the segment size. The size should be a multiple of the chunk size and allow 128 KB for the RAID superblock. Use a disk partitioner such as the YaST partitioner or the command line tool parted to decrease the size of the partition.

  5. Re-add the partition to the RAID array. For example, to add /dev/sda1, enter

    sudo mdadm -a /dev/md0 /dev/sda1

    Wait until the RAID is synchronized and consistent before continuing with the next partition.

  6. Repeat these steps for each of the remaining component devices in the array. Ensure that you modify the commands for the correct component partition.

  7. If you get a message that tells you that the kernel could not re-read the partition table for the RAID, you must reboot the computer after resizing all of its component partitions.

  8. (Optional) Expand the size of the RAID and file system to use the maximum amount of space in the now smaller component partitions and increase the size of the file system afterward. Refer to Section 11.1.2, “Increasing the Size of the RAID Array” for instructions.

12 Storage Enclosure LED Utilities for MD Software RAIDs

  • Filename: storage_raid-leds.xml
  • ID: cha.raid_leds
Abstract

Storage enclosure LED Monitoring utility (ledmon) and LED Control (ledctl) utility are Linux user space applications that use a broad range of interfaces and protocols to control storage enclosure LEDs. The primary usage is to visualize the status of Linux MD software RAID devices created with the mdadm utility. The ledmon daemon monitors the status of the drive array and updates the status of the drive LEDs. The ledctl utility allows you to set LED patterns for specified devices.

These LED utilities use the SGPIO (Serial General Purpose Input/Output) specification (Small Form Factor (SFF) 8485) and the SCSI Enclosure Services (SES) 2 protocol to control LEDs. They implement the International Blinking Pattern Interpretation (IBPI) patterns of the SFF-8489 specification for SGPIO. The IBPI defines how the SGPIO standards are interpreted as states for drives and slots on a backplane and how the backplane should visualize the states with LEDs.

Some storage enclosures do not adhere strictly to the SFF-8489 specification. An enclosure processor might accept an IBPI pattern but not blink the LEDs according to the SFF-8489 specification, or the processor might support only a limited number of the IBPI patterns.

LED management (AHCI) and SAF-TE protocols are not supported by the ledmon and ledctl utilities.

The ledmon and ledctl applications have been verified to work with Intel storage controllers such as the Intel AHCI controller and Intel SAS controller. They also support PCIe-SSD (solid-state drive) enclosure LEDs to control the storage enclosure status (OK, Fail, Rebuilding) LEDs of PCIe-SSD devices that are part of an MD software RAID volume. The applications might also work with the IBPI-compliant storage controllers of other vendors (especially SAS/SCSI controllers); however, other vendors’ controllers have not been tested.

ledmon and ledctl are part of the ledmon package, which is not installed by default. Run sudo zypper in ledmon to install it.

12.1 The Storage Enclosure LED Monitor Service

The ledmon application is a daemon process that constantly monitors the state of MD software RAID devices or the state of block devices in a storage enclosure or drive bay. Only a single instance of the daemon should be running at a time. The ledmon daemon is part of Intel Enclosure LED Utilities.

The state is visualized on LEDs associated with each slot in a storage array enclosure or a drive bay. The application monitors all software RAID devices and visualizes their state. It does not provide a way to monitor only selected software RAID volumes.

The ledmon daemon supports two types of LED systems: A two-LED system (Activity LED and Status LED) and a three-LED system (Activity LED, Locate LED, and Fail LED). This tool has the highest priority when accessing the LEDs.

To start ledmon, enter

sudo ledmon [options]

where [options] is one or more of the following:

Options for ledmon
-c PATH , --confg=PATH

The configuration is read from ~/.ledctl or from /etc/ledcfg.conf if existing. Use this option to specify an alternative configuration file.

Currently this option has no effect, since support for configuration files has not been implemented yet. See man 5 ledctl.conf for details.

-l PATH , --log=PATH

Sets a path to local log file. If this user-defined file is specified, the global log file /var/log/ledmon.log is not used.

-t SECONDS , --interval=SECONDS

Sets the time interval between scans of sysfs. The value is given in seconds. The minimum is 5 seconds. The maximum is not specified.

--quiet, --error, --warning, --info, --debug, --all

Specifies the verbosity level. The level options are specified in the order of no information to the most information. Use the --quiet option for no logging. Use the --all option to log everything. If you specify more than one verbose option, the last option in the command applies.

-h , --help

Prints the command information to the console, then exits.

-v , --version

Displays version of ledmon and information about the license, then exits.

Note
Note: Known Issues

The ledmon daemon does not recognize the PFA (Predicted Failure Analysis) state from the SFF-8489 specification. Thus, the PFA pattern is not visualized.

12.2 The Storage Enclosure LED Control Application

The Enclosure LED Application (ledctl) is a user space application that controls LEDs associated with each slot in a storage enclosure or a drive bay. The ledctl application is a part of Intel Enclosure LED Utilities.

When you issue the command, the LEDs of the specified devices are set to a specified pattern and all other LEDs are turned off. This application needs to be run with root privileges. Because the ledmon application has the highest priority when accessing LEDs, some patterns set by ledctl might have no effect if the ledmon daemon is running (except for the Locate pattern).

The ledctl application supports two types of LED systems: A two-LED system (Activity LED and Status LED) and a three-LED system (Activity LED, Fail LED, and Locate LED).

To start ledctl, enter

sudo [options] PATTERN_NAME=list_of_devices

where [options] is one or more of the following:

-c PATH , --confg=PATH

Sets a path to local configuration file. If this option is specified, the global configuration file and user configuration file have no effect.

-l PATH , --log=PATH

Sets a path to local log file. If this user-defined file is specified, the global log file /var/log/ledmon.log is not used.

--quiet

Turns off all messages sent to stdout or stderr out. The messages are still logged to local file and the syslog facility.

-h , --help

Prints the command information to the console, then exits.

-v , --version

Displays version of ledctl and information about the license, then exits.

12.2.1 Pattern Names

The ledctl application accepts the following names for pattern_name argument, according to the SFF-8489 specification.

locate

Turns on the Locate LED associated with the specified devices or empty slots. This state is used to identify a slot or drive.

locate_off

Turns off the Locate LED associated with the specified devices or empty slots.

normal

Turns off the Status LED, Failure LED, and Locate LED associated with the specified devices.

off

Turns off only the Status LED and Failure LED associated with the specified devices.

ica , degraded

Visualizes the In a Critical Array pattern.

rebuild , rebuild_p

Visualizes the Rebuild pattern. This supports both of the rebuild states for compatibility and legacy reasons.

ifa , failed_array

Visualizes the In a Failed Array pattern.

hotspare

Visualizes the Hotspare pattern.

pfa

Visualizes the Predicted Failure Analysis pattern.

failure , disk_failed

Visualizes the Failure pattern.

ses_abort

SES-2 R/R ABORT

ses_rebuild

SES-2 REBUILD/REMAP

ses_ifa

SES-2 IN FAILED ARRAY

ses_ica

SES-2 IN CRITICAL ARRAY

ses_cons_check

SES-2 CONS CHECK

ses_hotspare

SES-2 HOTSPARE

ses_rsvd_dev

SES-2 RSVD DEVICE

ses_ok

SES-2 OK

ses_ident

SES-2 IDENT

ses_rm

SES-2 REMOVE

ses_insert

SES-2 INSERT

ses_missing

SES-2 MISSING

ses_dnr

SES-2 DO NOT REMOVE

ses_active

SES-2 ACTIVE

ses_enable_bb

SES-2 ENABLE BYP B

ses_enable_ba

SES-2 ENABLE BYP A

ses_devoff

SES-2 DEVICE OFF

ses_fault

SES-2 FAULT

When a non-SES-2 pattern is sent to a device in an enclosure, the pattern is automatically translated to the SCSI Enclosure Services (SES) 2 pattern as shown above.

Table 12.1: Translation between Non-SES-2 Patterns and SES-2 Patterns

Non-SES-2 Pattern

SES-2 Pattern

locate

ses_ident

locate_off

ses_ident

normal

ses_ok

off

ses_ok

ica

ses_ica

degraded

ses_ica

rebuild

ses_rebuild

rebuild_p

ses_rebuild

ifa

ses_ifa

failed_array

ses_ifa

hotspare

ses_hotspare

pfa

ses_rsvd_dev

failure

ses_fault

disk_failed

ses_fault

12.2.2 List of Devices

When you issue the ledctl command, the LEDs of the specified devices are set to the specified pattern and all other LEDs are turned off. The list of devices can be provided in one of two formats:

  • A list of devices separated by a comma and no spaces

  • A list in curly braces with devices separated by a space

If you specify multiple patterns in the same command, the device list for each pattern can use the same or different format. For examples that show the two list formats, see Section 12.2.3, “Examples”.

A device is a path to file in the /dev directory or in the /sys/block directory. The path can identify a block device, an MD software RAID device, or a container device. For a software RAID device or a container device, the reported LED state is set for all of the associated block devices.

The LEDs of devices listed in list_of_devices are set to the given pattern pattern_name and all other LEDs are turned off.

12.2.3 Examples

To locate a single block device:

sudo ledctl locate=/dev/sda

To turn off the Locate LED for a single block device:

sudo ledctl locate_off=/dev/sda

To locate disks of an MD software RAID device and to set a rebuild pattern for two of its block devices at the same time:

sudo ledctl locate=/dev/md127 rebuild={ /sys/block/sd[a-b] }

To turn off the Status LED and Failure LED for the specified devices:

sudo ledctl off={ /dev/sda /dev/sdb }

To locate three block devices run one of the following commends (both are equivalent):

sudo ledctl locate=/dev/sda,/dev/sdb,/dev/sdc
sudo ledctl locate={ /dev/sda /dev/sdb /dev/sdc }

12.3 Additional Information

See the following resources for details about the LED patterns and monitoring tools:

Part IV Network Storage

13 iSNS for Linux

Storage area networks (SANs) can contain many disk drives that are dispersed across complex networks. This can make device discovery and device ownership difficult. iSCSI initiators must be able to identify storage resources in the SAN and determine whether they have access to them.

14 Mass Storage over IP Networks: iSCSI

One of the primary tasks of a computer center, or any site that supports servers, is to provide adequate disk capacity. Fibre Channel is often used for this purpose. iSCSI (Internet SCSI) solutions provide a lower-cost alternative to Fibre Channel that can leverage commodity servers and Ethernet net…

15 Fibre Channel Storage over Ethernet Networks: FCoE

Many enterprise data centers rely on Ethernet for their LAN and data traffic, and on Fibre Channel networks for their storage infrastructure. Open Fibre Channel over Ethernet (FCoE) Initiator software allows servers with Ethernet adapters to connect to a Fibre Channel storage subsystem over an Ether…

16 NVMe over Fabric

This chapter describes how to set up an NVMe over Fabric host and target.

17 Managing Multipath I/O for Devices

This section describes how to manage failover and path load balancing for multiple paths between the servers and block storage devices by using Multipath I/O (MPIO).

18 Managing Access Control Lists over NFSv4

There is no single standard for Access Control Lists (ACLs) in Linux beyond the simple read, write, and execute (rwx) flags for user, group, and others (ugo). One option for finer control is the Draft POSIX ACLs, which were never formally standardized by POSIX. Another is the NFSv4 ACLs, which were …

13 iSNS for Linux

  • Filename: storage_isns.xml
  • ID: cha.isns

Storage area networks (SANs) can contain many disk drives that are dispersed across complex networks. This can make device discovery and device ownership difficult. iSCSI initiators must be able to identify storage resources in the SAN and determine whether they have access to them.

Internet Storage Name Service (iSNS) is a standards-based service that simplifies the automated discovery, management, and configuration of iSCSI devices on a TCP/IP network. iSNS provides intelligent storage discovery and management services comparable to those found in Fibre Channel networks.

Important
Important: Security Considerations

iSNS should be used only in secure internal networks.

13.1 How iSNS Works

For an iSCSI initiator to discover iSCSI targets, it needs to identify which devices in the network are storage resources and what IP addresses it needs to access them. A query to an iSNS server returns a list of iSCSI targets and the IP addresses that the initiator has permission to access.

Using iSNS, you create iSNS discovery domains into which you then group or organize iSCSI targets and initiators. By dividing storage nodes into domains, you can limit the discovery process of each host to the most appropriate subset of targets registered with iSNS, which allows the storage network to scale by reducing the number of unnecessary discoveries and by limiting the amount of time each host spends establishing discovery relationships. This lets you control and simplify the number of targets and initiators that must be discovered.

iSNS Discovery Domains
Figure 13.1: iSNS Discovery Domains

Both iSCSI targets and iSCSI initiators use iSNS clients to initiate transactions with iSNS servers by using the iSNS protocol. They then register device attribute information in a common discovery domain, download information about other registered clients, and receive asynchronous notification of events that occur in their discovery domain.

iSNS servers respond to iSNS protocol queries and requests made by iSNS clients using the iSNS protocol. iSNS servers initiate iSNS protocol state change notifications and store properly authenticated information submitted by a registration request in an iSNS database.

Benefits provided by iSNS for Linux include:

  • Provides an information facility for registration, discovery, and management of networked storage assets.

  • Integrates with the DNS infrastructure.

  • Consolidates registration, discovery, and management of iSCSI storage.

  • Simplifies storage management implementations.

  • Improves scalability compared to other discovery methods.

An example of the benefits iSNS provides can be better understood through the following scenario:

Suppose you have a company that has 100 iSCSI initiators and 100 iSCSI targets. Depending on your configuration, all iSCSI initiators could potentially try to discover and connect to any of the 100 iSCSI targets. This could create discovery and connection difficulties. By grouping initiators and targets into discovery domains, you can prevent iSCSI initiators in one department from discovering the iSCSI targets in another department. The result is that the iSCSI initiators in a specific department only discover those iSCSI targets that are part of the department's discovery domain.

13.2 Installing iSNS Server for Linux

iSNS Server for Linux is included with SUSE Linux Enterprise Server, but is not installed or configured by default. You need to install the package open-isns and configure the iSNS service.

Note
Note: iSNS and iSCSI on the Same Server

iSNS can be installed on the same server where iSCSI target or iSCSI initiator software is installed. Installing both the iSCSI target software and iSCSI initiator software on the same server is not supported.

To install iSNS for Linux:

  1. Start YaST and select Network Services › iSNS Server.

  2. In case open-isns is not installed yet, you are prompted to install it now. Confirm by clicking Install.

  3. The iSNS Service configuration dialog opens automatically to the Service tab.

  4. In Service Start, select one of the following:

    • When Booting:  The iSNS service starts automatically on server start-up.

    • Manually (Default):  The iSNS service must be started manually by entering sudo systemctl start isnsd at the server console of the server where you install it.

  5. Specify the following firewall settings:

    • Open Port in Firewall:  Select the check box to open the firewall and allow access to the service from remote computers. The firewall port is closed by default.

    • Firewall Details:  If you open the firewall port, the port is open on all network interfaces by default. Click Firewall Details to select interfaces on which to open the port, select the network interfaces to use, then click OK.

  6. Click OK to apply the configuration settings and complete the installation.

  7. Continue with Section 13.3, “Configuring iSNS Discovery Domains”.

13.3 Configuring iSNS Discovery Domains

For iSCSI initiators and targets to use the iSNS service, they must belong to a discovery domain.

Important
Important: The iSNS Service Must be Active

The iSNS service must be installed and running to configure iSNS discovery domains. For information, see Section 13.4, “Starting the iSNS Service”.

13.3.1 Creating iSNS Discovery Domains

A default discovery domain named default DD is automatically created when you install the iSNS service. The existing iSCSI targets and initiators that have been configured to use iSNS are automatically added to the default discovery domain.

To create a new discovery domain:

  1. Start YaST and under Network Services, select iSNS Server.

  2. Click the Discovery Domains tab.

    The Discovery Domains area lists all existing discovery domains. You can Create Discovery Domains, or Delete existing ones. Deleting a domain removes the members from the domain, but it does not delete the iSCSI node members.

    The Discovery Domain Members area lists all iSCSI nodes assigned to a selected discovery domain. Selecting a different discovery domain refreshes the list with members from that discovery domain. You can add and delete iSCSI nodes from a selected discovery domain. Deleting an iSCSI node removes it from the domain, but it does not delete the iSCSI node.

    Create iSCSI Node Member allows a node that is not yet registered to be added as a member of the discovery domain. When the iSCSI initiator or target registers this node, then it becomes part of this domain.

    When an iSCSI initiator performs a discovery request, the iSNS service returns all iSCSI node targets that are members of the same discovery domain.

  3. Click the Create Discovery Domain button.

    You can also select an existing discovery domain and click the Delete button to remove that discovery domain.

  4. Specify the name of the discovery domain you are creating, then click OK.

  5. Continue with Section 13.3.2, “Adding iSCSI Nodes to a Discovery Domain”.

13.3.2 Adding iSCSI Nodes to a Discovery Domain

  1. Start YaST and under Network Services, select iSNS Server.

  2. Click the iSCSI Nodes tab.

  3. Review the list of nodes to ensure that the iSCSI targets and initiators that you want to use the iSNS service are listed.

    If an iSCSI target or initiator is not listed, you might need to restart the iSCSI service on the node. You can do this by running

    sudo systemctl restart iscsid.socket
    sudo systemctl restart iscsi

    to restart an initiator or

    sudo systemctl restart target-isns

    to restart a target.

    You can select an iSCSI node and click the Delete button to remove that node from the iSNS database. This is useful if you are no longer using an iSCSI node or have renamed it.

    The iSCSI node is automatically added to the list (iSNS database) again when you restart the iSCSI service or reboot the server unless you remove or comment out the iSNS portion of the iSCSI configuration file.

  4. Click the Discovery Domains tab and select the desired discovery domain.

  5. Click Add existing iSCSI Node, select the node you want to add to the domain, then click Add Node.

  6. Repeat the previous step for as many nodes as you want to add to the discovery domain, then click Done when you are finished adding nodes.

    Note that an iSCSI node can belong to more than one discovery domain.

13.4 Starting the iSNS Service

iSNS must be started at the server where you install it. If you have not configured it to be started at boot time (see Section 13.2, “Installing iSNS Server for Linux” for details), enter the following command at a terminal console:

sudo systemctl start isnsd

You can also use the stop, status, and restart options with iSNS.

13.5 For More Information

For information, see the Linux iSNS for iSCSI project at http://sourceforge.net/projects/linuxisns/. The electronic mailing list for this project can be found at http://sourceforge.net/mailarchive/forum.php?forum_name=linuxisns-discussion.

General information about iSNS is available in RFC 4171: Internet Storage Name Service at http://www.ietf.org/rfc/rfc4171.

14 Mass Storage over IP Networks: iSCSI

  • Filename: storage_iscsi.xml
  • ID: cha.iscsi

One of the primary tasks of a computer center, or any site that supports servers, is to provide adequate disk capacity. Fibre Channel is often used for this purpose. iSCSI (Internet SCSI) solutions provide a lower-cost alternative to Fibre Channel that can leverage commodity servers and Ethernet networking equipment. Linux iSCSI provides iSCSI initiator and iSCSI LIO target software for connecting Linux servers to central storage systems.

iSCSI SAN with an iSNS Server
Figure 14.1: iSCSI SAN with an iSNS Server
Note
Note: LIO

LIO (http://linux-iscsi.org) is the standard open source multiprotocol SCSI target for Linux. LIO replaced the STGT (SCSI Target) framework as the standard unified storage target in Linux with Linux kernel version 2.6.38 and later. In SUSE Linux Enterprise Server 12 the iSCSI LIO Target Server replaces the iSCSI Target Server from previous versions.

iSCSI is a storage networking protocol that simplifies data transfers of SCSI packets over TCP/IP networks between block storage devices and servers. iSCSI target software runs on the target server and defines the logical units as iSCSI target devices. iSCSI initiator software runs on different servers and connects to the target devices to make the storage devices available on that server.

The iSCSI LIO target server and iSCSI initiator servers communicate by sending SCSI packets at the IP level in your LAN. When an application running on the initiator server starts an inquiry for an iSCSI LIO target device, the operating system produces the necessary SCSI commands. The SCSI commands are then embedded in IP packets and encrypted as necessary by software that is commonly known as the iSCSI initiator. The packets are transferred across the internal IP network to the corresponding iSCSI remote station, called the iSCSI LIO target server, or simply the iSCSI target.

Many storage solutions provide access over iSCSI, but it is also possible to run a Linux server that provides an iSCSI target. In this case, it is important to set up a Linux server that is optimized for file system services. The iSCSI target accesses block devices in Linux. Therefore, it is possible to use RAID solutions to increase disk space and a lot of memory to improve data caching. For more information about RAID, also see Chapter 7, Software RAID Configuration.

14.1 Installing the iSCSI LIO Target Server and iSCSI Initiator

While the iSCSI initiator is installed by default (packages open-iscsi and yast2-iscsi-client), the iSCSI LIO target packages need to be installed manually.

Important
Important: Initiator and Target may not Run on the Same Server

It is not supported to run iSCSI target software and iSCSI initiator software on the same server in a production environment.

To install the iSCSI LIO Target Server, run the following command in a terminal console:

sudo zypper in yast2-iscsi-lio-server

In case you need to install the iSCSI initiator or any of its dependencies, run the command sudo zypper in yast2-iscsi-client.

Alternatively, use the YaST Software Management module for installation.

Any packages required in addition to the ones mentioned above will either be automatically pulled in by the installer, or be installed when you first run the respective YaST module.

14.2 Setting Up an iSCSI LIO Target Server

This section describes how to use YaST to configure an iSCSI LIO Target Server and set up iSCSI LIO target devices. You can use any iSCSI initiator software to access the target devices.

14.2.1 iSCSI LIO Target Service Start-up and Firewall Settings

The iSCSI LIO Target service is by default configured to be started manually. You can configure the service to start automatically at boot time. If you use a firewall on the server and you want the iSCSI LIO targets to be available to other computers, you must open a port in the firewall for each adapter that you want to use for target access. TCP port 3260 is the port number for the iSCSI protocol, as defined by IANA (Internet Assigned Numbers Authority).

  1. Start YaST and launch Network Services › iSCSI LIO Target.

  2. Switch to the Service tab.

  3. Under Service Start, specify how you want the iSCSI LIO target service to be started:

    • When Booting:  The service starts automatically on server restart.

    • Manually:  (Default) You must start the service manually after a server restart by running sudo systemctl start target. The target devices are not available until you start the service.

  4. If you use a firewall on the server and you want the iSCSI LIO targets to be available to other computers, open port 3260 in the firewall for each adapter interface that you want to use for target access. If the port is closed for all of the network interfaces, the iSCSI LIO targets are not available to other computers.

    If you do not use a firewall on the server, the firewall settings are disabled. In this case skip the following steps and leave the configuration dialog with Finish or switch to another tab to continue with the configuration.

    1. On the Services tab, select the Open Port in Firewall check box to enable the firewall settings.

    2. Click Firewall Details to view or configure the network interfaces to use. All available network interfaces are listed, and all are selected by default. Deselect all interfaces on which the port should not be opened. Save your settings with OK.

  5. Click Finish to save and apply the iSCSI LIO Target service settings.

14.2.2 Configuring Authentication for Discovery of iSCSI LIO Targets and Initiators

The iSCSI LIO Target Server software supports the PPP-CHAP (Point-to-Point Protocol Challenge Handshake Authentication Protocol), a three-way authentication method defined in the Internet Engineering Task Force (IETF) RFC 1994 (http://www.ietf.org/rfc/rfc1994.txt). The server uses this authentication method for the discovery of iSCSI LIO targets and initiators, not for accessing files on the targets. If you do not want to restrict the access to the discovery, use No Authentication. The No Discovery Authentication option is enabled by default. Without requiring authentication all iSCSI LIO targets on this server can be discovered by any iSCSI initiator on the same network.

If authentication is needed for a more secure configuration, you can use incoming authentication, outgoing authentication, or both. Authentication by Initiators requires an iSCSI initiator to prove that it has the permissions to run a discovery on the iSCSI LIO target. The initiator must provide the incoming user name and password. Authentication by Targets requires the iSCSI LIO target to prove to the initiator that it is the expected target. The iSCSI LIO target must provide the outgoing user name and password to the iSCSI initiator. The password needs to be different for incoming and outgoing discovery. If authentication for discovery is enabled, its settings apply to all iSCSI LIO target groups.

Important
Important: Security

We recommend that you use authentication for target and initiator discovery in production environments for security reasons.

To configure authentication preferences for iSCSI LIO targets:

  1. Start YaST and launch Network Services › iSCSI LIO Target.

  2. Switch to the Global tab.

  3. By default, authentication is disabled (No Discovery Authentication). To enable Authentication, select Authentication by Initiators, Outgoing Authentication or both.

  4. Provide credentials for the selected authentication method(s). The user name and password pair must be different for incoming and outgoing discovery.

  5. Click Finish to save and apply the settings.

14.2.3 Preparing the Storage Space

Before you configure LUNs for your iSCSI Target servers, you must prepare the storage you want to use. You can use the entire unformatted block device as a single LUN, or you can subdivide a device into unformatted partitions and use each partition as a separate LUN. The iSCSI target configuration exports the LUNs to iSCSI initiators.

You can use the Partitioner in YaST or the command line to set up the partitions. Refer to Section 12.1, “Using the YaST Partitioner” for details. iSCSI LIO targets can use unformatted partitions with Linux, Linux LVM, or Linux RAID file system IDs.

Important
Important: Do Not Mount iSCSI Target Devices

After you set up a device or partition for use as an iSCSI target, you never access it directly via its local path. Do not mount the partitions on the target server.

14.2.3.1 Partitioning Devices in a Virtual Environment

You can use a virtual machine guest server as an iSCSI LIO Target Server. This section describes how to assign partitions to a Xen virtual machine. You can also use other virtual environments that are supported by SUSE Linux Enterprise Server.

In a Xen virtual environment, you must assign the storage space you want to use for the iSCSI LIO target devices to the guest virtual machine, then access the space as virtual disks within the guest environment. Each virtual disk can be a physical block device, such as an entire disk, partition, or volume, or it can be a file-backed disk image where the virtual disk is a single image file on a larger physical disk on the Xen host server. For the best performance, create each virtual disk from a physical disk or a partition. After you set up the virtual disks for the guest virtual machine, start the guest server, then configure the new blank virtual disks as iSCSI target devices by following the same process as for a physical server.

File-backed disk images are created on the Xen host server, then assigned to the Xen guest server. By default, Xen stores file-backed disk images in the /var/lib/xen/images/VM_NAME directory, where VM_NAME is the name of the virtual machine.

14.2.4 Setting Up an iSCSI LIO Target Group

You can use YaST to configure iSCSI LIO target devices. YaST uses APIs provided by the lio-utils software. iSCSI LIO targets can use unformatted partitions with Linux, Linux LVM, or Linux RAID file system IDs.

Important
Important: Partitions

Before you begin, create the unformatted partitions that you want to use as iSCSI LIO targets as described in Section 14.2.3, “Preparing the Storage Space”.

  1. Start YaST and launch Network Services › iSCSI LIO Target.

  2. Switch to the Targets tab.

  3. Click Add, then define a new iSCSI LIO target group and devices:

    The iSCSI LIO Target software automatically completes the Target, Identifier, Portal Group, IP Address, and Port Number fields. Use Authentication is selected by default.

    1. If you have multiple network interfaces, use the IP address drop-down box to select the IP address of the network interface to use for this target group. To make the server accessible under all addresses, choose Bind All IP Addresses.

    2. Deselect Use Authentication if you do not want to require initiator authentication for this target group (not recommended).

    3. Click Add. Enter the path of the device or partition or Browse to add it. Optionally specify a name, then click OK. The LUN number is automatically generated, beginning with 0. A name is automatically generated if you leave the field empty.

    4. (Optional) Repeat the previous steps to add more targets to this target group.

    5. After all desired targets have been added to the group, click Next.

  4. On the Modify iSCSI Target Initiator Setup page, configure information for the initiators that are permitted to access LUNs in the target group:

    After you specify at least one initiator for the target group, the Edit LUN, Edit Auth, Delete, and Copy buttons are enabled. You can use Add or Copy to add more initiators for the target group:

    Modify iSCSI Target: Options
    • Add:  Add a new initiator entry for the selected iSCSI LIO target group.

    • Edit LUN:  Configure which LUNs in the iSCSI LIO target group to map to a selected initiator. You can map each of the allocated targets to a preferred initiator.

    • Edit Auth:  Configure the preferred authentication method for a selected initiator. You can specify no authentication, or you can configure incoming authentication, outgoing authentication, or both.

    • Delete:  Remove a selected initiator entry from the list of initiators allocated to the target group.

    • Copy:  Add a new initiator entry with the same LUN mappings and authentication settings as a selected initiator entry. This allows you to easily allocate the same shared LUNs, in turn, to each node in a cluster.

    1. Click Add, specify the initiator name, select or deselect the Import LUNs from TPG check box, then click OK to save the settings.

    2. Select an initiator entry, click Edit LUN, modify the LUN mappings to specify which LUNs in the iSCSI LIO target group to allocate to the selected initiator, then click OK to save the changes.

      If the iSCSI LIO target group consists of multiple LUNs, you can allocate one or multiple LUNs to the selected initiator. By default, each of the available LUNs in the group are assigned to an initiator LUN.

      To modify the LUN allocation, perform one or more of the following actions:

      • Add:  Click Add to create a new Initiator LUN entry, then use the Change drop-down box to map a target LUN to it.

      • Delete:  Select the Initiator LUN entry, then click Delete to remove a target LUN mapping.

      • Change:  Select the Initiator LUN entry, then use the Change drop-down box to select which Target LUN to map to it.

      Typical allocation plans include the following:

      • A single server is listed as an initiator. All of the LUNs in the target group are allocated to it.

        You can use this grouping strategy to logically group the iSCSI SAN storage for a given server.

      • Multiple independent servers are listed as initiators. One or multiple target LUNs are allocated to each server. Each LUN is allocated to only one server.

        You can use this grouping strategy to logically group the iSCSI SAN storage for a given department or service category in the data center.

      • Each node of a cluster is listed as an initiator. All of the shared target LUNs are allocated to each node. All nodes are attached to the devices, but for most file systems, the cluster software locks a device for access and mounts it on only one node at a time. Shared file systems (such as OCFS2) make it possible for multiple nodes to concurrently mount the same file structure and to open the same files with read and write access.

        You can use this grouping strategy to logically group the iSCSI SAN storage for a given server cluster.

    3. Select an initiator entry, click Edit Auth, specify the authentication settings for the initiator, then click OK to save the settings.

      You can require No Discovery Authentication, or you can configure Authentication by Initiators, Outgoing Authentication, or both. You can specify only one user name and password pair for each initiator. The credentials can be different for incoming and outgoing authentication for an initiator. The credentials can be different for each initiator.

    4. Repeat the previous steps for each iSCSI initiator that can access this target group.

    5. After the initiator assignments are configured, click Next.

  5. Click Finish to save and apply the settings.

14.2.5 Modifying an iSCSI LIO Target Group

You can modify an existing iSCSI LIO target group as follows:

  • Add or remove target LUN devices from a target group

  • Add or remove initiators for a target group

  • Modify the initiator LUN-to-target LUN mappings for an initiator of a target group

  • Modify the user name and password credentials for an initiator authentication (incoming, outgoing, or both)

To view or modify the settings for an iSCSI LIO target group:

  1. Start YaST and launch Network Services › iSCSI LIO Target.

  2. Switch to the Targets tab.

  3. Select the iSCSI LIO target group to be modified, then click Edit.

  4. On the Modify iSCSI Target LUN Setup page, add LUNs to the target group, edit the LUN assignments, or remove target LUNs from the group. After all desired changes have been made to the group, click Next.

    For option information, see Modify iSCSI Target: Options.

  5. On the Modify iSCSI Target Initiator Setup page, configure information for the initiators that are permitted to access LUNs in the target group. After all desired changes have been made to the group, click Next.

  6. Click Finish to save and apply the settings.

14.2.6 Deleting an iSCSI LIO Target Group

Deleting an iSCSI LIO target group removes the definition of the group, and the related setup for initiators, including LUN mappings and authentication credentials. It does not destroy the data on the partitions. To give initiators access again, you can allocate the target LUNs to a different or new target group, and configure the initiator access for them.

  1. Start YaST and launch Network Services › iSCSI LIO Target.

  2. Switch to the Targets tab.

  3. Select the iSCSI LIO target group to be deleted, then click Delete.

  4. When you are prompted, click Continue to confirm the deletion, or click Cancel to cancel it.

  5. Click Finish to save and apply the settings.

14.3 Configuring iSCSI Initiator

The iSCSI initiator can be used to connect to any iSCSI target. This is not restricted to the iSCSI target solution explained in Section 14.2, “Setting Up an iSCSI LIO Target Server”. The configuration of iSCSI initiator involves two major steps: the discovery of available iSCSI targets and the setup of an iSCSI session. Both can be done with YaST.

14.3.1 Using YaST for the iSCSI Initiator Configuration

The iSCSI Initiator Overview in YaST is divided into three tabs:

Service:

The Service tab can be used to enable the iSCSI initiator at boot time. It also offers to set a unique Initiator Name and an iSNS server to use for the discovery.

Connected Targets:

The Connected Targets tab gives an overview of the currently connected iSCSI targets. Like the Discovered Targets tab, it also gives the option to add new targets to the system.

Discovered Targets:

The Discovered Targets tab provides the possibility of manually discovering iSCSI targets in the network.

14.3.1.1 Configuring the iSCSI Initiator

  1. Start YaST and launch Network Services › iSCSI Initiator.

  2. Switch to the Services tab.

  3. Under Service Start, specify how you want the iSCSI initiator service to be started:

    • When Booting:  The service starts automatically on server restart.

    • Manually:  (Default) You must start the service manually after a server restart by running sudo systemctl start iscsi iscsid.

  4. Specify or verify the Initiator Name.

    Specify a well-formed iSCSI qualified name (IQN) for the iSCSI initiator on this server. The initiator name must be globally unique on your network. The IQN uses the following general format:

    iqn.yyyy-mm.com.mycompany:n1:n2

    where n1 and n2 are alphanumeric characters. For example:

    iqn.1996-04.de.suse:01:a5dfcea717a

    The Initiator Name is automatically completed with the corresponding value from the /etc/iscsi/initiatorname.iscsi file on the server.

    If the server has iBFT (iSCSI Boot Firmware Table) support, the Initiator Name is completed with the corresponding value in the IBFT, and you are not able to change the initiator name in this interface. Use the BIOS Setup to modify it instead. The iBFT is a block of information containing various parameters useful to the iSCSI boot process, including iSCSI target and initiator descriptions for the server.

  5. Use either of the following methods to discover iSCSI targets on the network.

14.3.1.2 Discovering iSCSI Targets by Using iSNS

Before you can use this option, you must have already installed and configured an iSNS server in your environment. For information, see Chapter 13, iSNS for Linux.

  1. In YaST, select iSCSI Initiator, then select the Service tab.

  2. Specify the IP address of the iSNS server and port. The default port is 3205.

  3. Click OK to save and apply your changes.

14.3.1.3 Discovering iSCSI Targets Manually

Repeat the following process for each of the iSCSI target servers that you want to access from the server where you are setting up the iSCSI initiator.

  1. In YaST, select iSCSI Initiator, then select the Discovered Targets tab.

  2. Click Discovery to open the iSCSI Initiator Discovery dialog.

  3. Enter the IP address and change the port if needed. The default port is 3260.

  4. If authentication is required, deselect No Discovery Authentication, then specify the credentials for Authentication by Initiator or Authentication by Targets.

  5. Click Next to start the discovery and connect to the iSCSI target server.

  6. If credentials are required, after a successful discovery, use Connect to activate the target.

    You are prompted for authentication credentials to use the selected iSCSI target.

  7. Click Next to finish the configuration.

    The target now appears in Connected Targets and the virtual iSCSI device is now available.

  8. Click OK to save and apply your changes.

  9. You can find the local device path for the iSCSI target device by using the lsscsi command.

14.3.1.4 Setting the Start-up Preference for iSCSI Target Devices

  1. In YaST, select iSCSI Initiator, then select the Connected Targets tab to view a list of the iSCSI target devices that are currently connected to the server.

  2. Select the iSCSI target device that you want to manage.

  3. Click Toggle Start-Up to modify the setting:

    Automatic:  This option is used for iSCSI targets that are to be connected when the iSCSI service itself starts up. This is the typical configuration.

    Onboot:  This option is used for iSCSI targets that are to be connected during boot; that is, when root (/) is on iSCSI. As such, the iSCSI target device will be evaluated from the initrd on server boots. This option is ignored on platforms that cannot boot from iSCSI, such as IBM z Systems. Therefore it should not be used on these platforms; use Automatic instead.

  4. Click OK to save and apply your changes.

14.3.2 Setting Up the iSCSI Initiator Manually

Both the discovery and the configuration of iSCSI connections require a running iscsid. When running the discovery the first time, the internal database of the iSCSI initiator is created in the directory /etc/iscsi/.

If your discovery is password protected, provide the authentication information to iscsid. Because the internal database does not exist when doing the first discovery, it cannot be used now. Instead, the configuration file /etc/iscsid.conf must be edited to provide the information. To add your password information for the discovery, add the following lines to the end of /etc/iscsid.conf:

discovery.sendtargets.auth.authmethod = CHAP
discovery.sendtargets.auth.username = USERNAME
discovery.sendtargets.auth.password = PASSWORD

The discovery stores all received values in an internal persistent database. In addition, it displays all detected targets. Run this discovery with the following command:

sudo iscsiadm -m discovery --type=st --portal=TARGET_IP

The output should look like the following:

10.44.171.99:3260,1 iqn.2006-02.com.example.iserv:systems

To discover the available targets on an iSNS server, use the following command:

sudo iscsiadm --mode discovery --type isns --portal TARGET_IP

For each target defined on the iSCSI target, one line appears. For more information about the stored data, see Section 14.3.3, “The iSCSI Initiator Databases”.

The special --login option of iscsiadm creates all needed devices:

sudo iscsiadm -m node -n iqn.2006-02.com.example.iserv:systems --login

The newly generated devices show up in the output of lsscsi and can now be mounted.

14.3.3 The iSCSI Initiator Databases

All information that was discovered by the iSCSI initiator is stored in two database files that reside in /etc/iscsi. There is one database for the discovery of targets and one for the discovered nodes. When accessing a database, you first must select if you want to get your data from the discovery or from the node database. Do this with the -m discovery and -m node parameters of iscsiadm. Using iscsiadm with one of these parameters gives an overview of the stored records:

tux > sudo iscsiadm -m discovery
10.44.171.99:3260,1 iqn.2006-02.com.example.iserv:systems

The target name in this example is iqn.2006-02.com.example.iserv:systems. This name is needed for all actions that relate to this special data set. To examine the content of the data record with the ID iqn.2006-02.com.example.iserv:systems, use the following command:

tux > sudo iscsiadm -m node --targetname iqn.2006-02.com.example.iserv:systems
node.name = iqn.2006-02.com.example.iserv:systems
node.transport_name = tcp
node.tpgt = 1
node.active_conn = 1
node.startup = manual
node.session.initial_cmdsn = 0
node.session.reopen_max = 32
node.session.auth.authmethod = CHAP
node.session.auth.username = joe
node.session.auth.password = ********
node.session.auth.username_in = EMPTY
node.session.auth.password_in = EMPTY
node.session.timeo.replacement_timeout = 0
node.session.err_timeo.abort_timeout = 10
node.session.err_timeo.reset_timeout = 30
node.session.iscsi.InitialR2T = No
node.session.iscsi.ImmediateData = Yes
....

To edit the value of one of these variables, use the command iscsiadm with the update operation. For example, if you want iscsid to log in to the iSCSI target when it initializes, set the variable node.startup to the value automatic:

sudo iscsiadm -m node -n iqn.2006-02.com.example.iserv:systems \
-p ip:port --op=update --name=node.startup --value=automatic

Remove obsolete data sets with the delete operation. If the target iqn.2006-02.com.example.iserv:systems is no longer a valid record, delete this record with the following command:

sudo iscsiadm -m node -n iqn.2006-02.com.example.iserv:systems \
-p ip:port --op=delete
Important
Important: No Confirmation

Use this option with caution because it deletes the record without any additional confirmation prompt.

To get a list of all discovered targets, run the sudo iscsiadm -m node command.

14.4 Using iSCSI Disks when Installing

Booting from an iSCSI disk on AMD64/Intel 64 and IBM POWER architectures is supported when iSCSI-enabled firmware is used.

To use iSCSI disks during installation, it is necessary to add the following parameter to the boot option line:

withiscsi=1

During installation, an additional screen appears that provides the option to attach iSCSI disks to the system and use them in the installation process.

Note
Note: Mount Point Support

iSCSI devices will appear asynchronously during the boot process. While the initrd guarantees that those devices are set up correctly for the root file system, there are no such guarantees for any other file systems or mount points like /usr. Hence any system mount points like /usr or /var are not supported. To use those devices, ensure correct synchronization of the respective services and devices.

14.5 Troubleshooting iSCSI

This section describes some known issues and possible solutions for iSCSI target and iSCSI initiator issues.

14.5.1 Portal Error When Setting Up Target LUNs on an iSCSI LIO Target Server

When adding or editing an iSCSI LIO target group, you get an error:

Problem setting network portal IP_ADDRESS:3260

The /var/log/YasT2/y2log log file contains the following error:

find: `/sys/kernel/config/target/iscsi': No such file or directory

This problem occurs if the iSCSI LIO Target Server software is not currently running. To resolve this issue, exit YaST, manually start iSCSI LIO at the command line with systemctl start target, then try again.

You can also enter the following to check if configfs, iscsi_target_mod, and target_core_mod are loaded. A sample response is shown.

tux > sudo lsmod | grep iscsi
iscsi_target_mod      295015  0
target_core_mod       346745  4
iscsi_target_mod,target_core_pscsi,target_core_iblock,target_core_file
configfs               35817  3 iscsi_target_mod,target_core_mod
scsi_mod              231620  16
iscsi_target_mod,target_core_pscsi,target_core_mod,sg,sr_mod,mptctl,sd_mod,
scsi_dh_rdac,scsi_dh_emc,scsi_dh_alua,scsi_dh_hp_sw,scsi_dh,libata,mptspi,
mptscsih,scsi_transport_spi

14.5.2 iSCSI LIO Targets Are Not Visible from Other Computers

If you use a firewall on the target server, you must open the iSCSI port that you are using to allow other computers to see the iSCSI LIO targets. For information, see Section 14.2.1, “iSCSI LIO Target Service Start-up and Firewall Settings”.

14.5.3 Data Packets Dropped for iSCSI Traffic

A firewall might drop packets if it gets too busy. The default for the SUSE Firewall is to drop packets after three minutes. If you find that iSCSI traffic packets are being dropped, you can consider configuring the SUSE Firewall to queue packets instead of dropping them when it gets too busy.

14.5.4 Using iSCSI Volumes with LVM

Use the troubleshooting tips in this section when using LVM on iSCSI targets.

14.5.4.1 Check if the iSCSI Initiator Discovery Occurs at Boot

When you set up the iSCSI Initiator, ensure that you enable discovery at boot time so that udev can discover the iSCSI devices at boot time and set up the devices to be used by LVM.

14.5.4.2 Check that iSCSI Target Discovery Occurs at Boot

Remember that udev provides the default setup for devices. Ensure that all of the applications that create devices are started at boot time so that udev can recognize and assign devices for them at system start-up. If the application or service is not started until later, udev does not create the device automatically as it would at boot time.

14.5.5 iSCSI Targets Are Mounted When the Configuration File Is Set to Manual

When Open-iSCSI starts, it can mount the targets even if the node.startup option is set to manual in the /etc/iscsi/iscsid.conf file if you manually modified the configuration file.

Check the /etc/iscsi/nodes/TARGET_NAME/IP_ADDRESS,PORT/default file. It contains a node.startup setting that overrides the /etc/iscsi/iscsid.conf file. Setting the mount option to manual by using the YaST interface also sets node.startup = manual in the /etc/iscsi/nodes/TARGET_NAME/IP_ADDRESS,PORT/default files.

14.6 iSCSI LIO Target Terminology

backstore

A physical storage object that provides the actual storage underlying an iSCSI endpoint.

CDB (command descriptor block)

The standard format for SCSI commands. CDBs are commonly 6, 10, or 12 bytes long, though they can be 16 bytes or of variable length.

CHAP (Challenge Handshake Authentication Protocol)

A point-to-point protocol (PPP) authentication method used to confirm the identity of one computer to another. After the Link Control Protocol (LCP) connects the two computers, and the CHAP method is negotiated, the authenticator sends a random Challenge to the peer. The peer issues a cryptographically hashed Response that depends upon the Challenge and a secret key. The authenticator verifies the hashed Response against its own calculation of the expected hash value, and either acknowledges the authentication or terminates the connection. CHAP is defined in the RFC 1994.

CID (connection identifier)

A 16‐bit number, generated by the initiator, that uniquely identifies a connection between two iSCSI devices. This number is presented during the login phase.

endpoint

The combination of an iSCSI Target Name with an iSCSI TPG (IQN + Tag).

EUI (extended unique identifier)

A 64‐bit number that uniquely identifies every device in the world. The format consists of 24 bits that are unique to a given company, and 40 bits assigned by the company to each device it builds.

initiator

The originating end of an SCSI session. Typically a controlling device such as a computer.

IPS (Internet Protocol storage)

The class of protocols or devices that use the IP protocol to move data in a storage network. FCIP (Fibre Channel over Internet Protocol), iFCP (Internet Fibre Channel Protocol), and iSCSI (Internet SCSI) are all examples of IPS protocols.

IQN (iSCSI qualified name)

A name format for iSCSI that uniquely identifies every device in the world (for example: iqn.5886.com.acme.tapedrive.sn‐a12345678).

ISID (initiator session identifier)

A 48‐bit number, generated by the initiator, that uniquely identifies a session between the initiator and the target. This value is created during the login process, and is sent to the target with a Login PDU.

MCS (multiple connections per session)

A part of the iSCSI specification that allows multiple TCP/IP connections between an initiator and a target.

MPIO (multipath I/O)

A method by which data can take multiple redundant paths between a server and storage.

network portal

The combination of an iSCSI endpoint with an IP address plus a TCP (Transmission Control Protocol) port. TCP port 3260 is the port number for the iSCSI protocol, as defined by IANA (Internet Assigned Numbers Authority).

SAM (SCSI architectural model)

A document that describes the behavior of SCSI in general terms, allowing for different types of devices communicating over various media.

target

The receiving end of an SCSI session, typically a device such as a disk drive, tape drive, or scanner.

target group (TG)

A list of SCSI target ports that are all treated the same when creating views. Creating a view can help simplify LUN (logical unit number) mapping. Each view entry specifies a target group, host group, and a LUN.

target port

The combination of an iSCSI endpoint with one or more LUNs.

target port group (TPG)

A list of IP addresses and TCP port numbers that determines which interfaces a specific iSCSI target will listen to.

target session identifier (TSID)

A 16‐bit number, generated by the target, that uniquely identifies a session between the initiator and the target. This value is created during the login process, and is sent to the initiator with a Login Response PDU (protocol data units).

14.7 Additional Information

The iSCSI protocol has been available for several years. There are many reviews comparing iSCSI with SAN solutions, benchmarking performance, and there also is documentation describing hardware solutions. Important pages for more information about open-iscsi are:

There is also some online documentation available. See the man pages for iscsiadm, iscsid, ietd.conf, and ietd and the example configuration file /etc/iscsid.conf.

15 Fibre Channel Storage over Ethernet Networks: FCoE

  • Filename: storage_fcoe.xml
  • ID: cha.fcoe

Many enterprise data centers rely on Ethernet for their LAN and data traffic, and on Fibre Channel networks for their storage infrastructure. Open Fibre Channel over Ethernet (FCoE) Initiator software allows servers with Ethernet adapters to connect to a Fibre Channel storage subsystem over an Ethernet network. This connectivity was previously reserved exclusively for systems with Fibre Channel adapters over a Fibre Channel fabric. The FCoE technology reduces complexity in the data center by aiding network convergence. This helps to preserve your existing investments in a Fibre Channel storage infrastructure and to simplify network management.

Open Fibre Channel over Ethernet SAN
Figure 15.1: Open Fibre Channel over Ethernet SAN

Open-FCoE allows you to run the Fibre Channel protocols on the host, instead of on proprietary hardware on the host bus adapter. It is targeted for 10 Gbps (gigabit per second) Ethernet adapters, but can work on any Ethernet adapter that supports pause frames. The initiator software provides a Fibre Channel protocol processing module and an Ethernet-based transport module. The Open-FCoE module acts as a low-level driver for SCSI. The Open-FCoE transport uses net_device to send and receive packets. Data Center Bridging (DCB) drivers provide the quality of service for FCoE.

FCoE is an encapsulation protocol that moves the Fibre Channel protocol traffic over Ethernet connections without changing the Fibre Channel frame. This allows your network security and traffic management infrastructure to work the same with FCoE as it does with Fibre Channel.

You might choose to deploy FCoE in your enterprise if the following conditions exist:

  • Your enterprise already has a Fibre Channel storage subsystem and administrators with Fibre Channel skills and knowledge.

  • You are deploying 10 Gbps Ethernet in the network.

This section describes how to set up FCoE in your network.

15.1 Configuring FCoE Interfaces during the Installation

The YaST installation for SUSE Linux Enterprise Server allows you to configure FCoE disks during the operating system installation if FCoE is enabled at the switch for the connections between the server and the Fibre Channel storage infrastructure. Some system BIOS types can automatically detect the FCoE disks, and report the disks to the YaST Installation software. However, automatic detection of FCoE disks is not supported by all BIOS types. To enable automatic detection in this case, you can add the withfcoe option to the kernel command line when you begin the installation:

withfcoe=1

When the FCoE disks are detected, the YaST installation offers the option to configure FCoE instances at that time. On the Disk Activation page, select Configure FCoE Interfaces to access the FCoE configuration. For information about configuring the FCoE interfaces, see Section 15.3, “Managing FCoE Services with YaST”.

Note
Note: Mount Point Support

FCoE devices will appear asynchronously during the boot process. While the initrd guarantees that those devices are set up correctly for the root file system, there are no such guarantees for any other file systems or mount points like /usr. Hence any system mount points like /usr or /var are not supported. To use those devices, ensure correct synchronization of the respective services and devices.

15.2 Installing FCoE and the YaST FCoE Client

You can set up FCoE disks in your storage infrastructure by enabling FCoE at the switch for the connections to a server. If FCoE disks are available when the SUSE Linux Enterprise Server operating system is installed, the FCoE Initiator software is automatically installed at that time.

If the FCoE Initiator software and the YaST FCoE Client software are not installed, use the following procedure to manually install them with the following command:

sudo zypper in yast2-fcoe-client fcoe-utils

Alternatively, use the YaST Software Manager to install the packages listed above.

15.3 Managing FCoE Services with YaST

You can use the YaST FCoE Client Configuration option to create, configure, and remove FCoE interfaces for the FCoE disks in your Fibre Channel storage infrastructure. To use this option, the FCoE Initiator service (the fcoemon daemon) and the Link Layer Discovery Protocol agent daemon (llpad) must be installed and running, and the FCoE connections must be enabled at the FCoE-capable switch.

  1. Launch YaST and select Network Services › FCoE Client Configuration.

  2. On the Services tab, view or modify the FCoE service and Lldpad (Link Layer Discovery Protocol agent daemon) service start time as necessary.

    • FCoE Service Start:  Specifies whether to start the Fibre Channel over Ethernet service fcoemon daemon at the server boot time or manually. The daemon controls the FCoE interfaces and establishes a connection with the llpad daemon. The values are When Booting (default) or Manually.

    • Lldpad Service Start:  Specifies whether to start the Link Layer Discovery Protocol agent llpad daemon at the server boot time or manually. The llpad daemon informs the fcoemon daemon about the Data Center Bridging features and the configuration of the FCoE interfaces. The values are When Booting (default) or Manually.

    If you modify a setting, click OK to save and apply the change.

  3. On the Interfaces tab, view information about all of the detected network adapters on the server, including information about VLAN and FCoE configuration. You can also create an FCoE VLAN interface, change settings for an existing FCoE interface, or remove an FCoE interface.

    Use the FCoE VLAN Interface column to determine whether FCoE is available or not:

    Interface Name

    If a name is assigned to the interface, such as eth4.200, FCoE is available on the switch, and the FCoE interface is activated for the adapter.

    Not Configured:

    If the status is not configured, FCoE is enabled on the switch, but an FCoE interface has not been activated for the adapter. Select the adapter, then click Create FCoE VLAN Interface to activate the interface on the adapter.

    Not Available:

    If the status is not available, FCoE is not possible for the adapter because FCoE has not been enabled for that connection on the switch.

  4. To set up an FCoE-enabled adapter that has not yet been configured, select it and click Create FCoE VLAN Interface. Confirm the query with Yes.

    The adapter is now listed with an interface name in the FCoE VLAN Interface column.

  5. To change the settings for an adapter that is already configured, select it from the list, then click Change Settings.

    The following options can be configured:

    FCoE Enable

    Enable or disable the creation of FCoE instances for the adapter.

    DCB Required

    Specifies whether Data Center Bridging is required for the adapter (usually this is the case).

    Auto VLAN

    Specifies whether the fcoemon daemon creates the VLAN interfaces automatically.

    If you modify a setting, click Next to save and apply the change. The settings are written to the /etc/fcoe/cfg-ethX file. The fcoemon daemon reads the configuration files for each FCoE interface when it is initialized.

  6. To remove an interface that is already configured, select it from the list. Click Remove Interface and Continue to confirm. The FCoE Interface value changes to not configured.

  7. On the Configuration tab, view or modify the general settings for the FCoE system service. You can enable or disable debugging messages from the FCoE service script and the fcoemon daemon and specify whether messages are sent to the system log.

  8. Click OK to save and apply changes.

15.4 Configuring FCoE with Commands

  1. Open a terminal console.

  2. Use YaST to configure the Ethernet network interface card, such as eth2.

  3. Start the Link Layer Discovery Protocol agent daemon (llpad).

    sudo systemctl start lldpad
  4. Enable Data Center Bridging on your Ethernet adapter.

    tux > dcbtool sc eth2 dcb on
      Version:       2
      Command:       Set Config
      Feature:       DCB State
      Port:          eth2
      Status:        Successful
  5. Enable and set the Priority Flow Control (PFC) settings for Data Center Bridging.

    sudo dcbtool sc eth<x> pfc e:1 a:1 w:1

    Argument setting values are:

    e:<0|1>

    Controls feature enablement.

    a:<0|1>

    Controls whether the feature is advertised via Data Center Bridging Exchange protocol to the peer.

    w:<0|1>

    Controls whether the feature is willing to change its operational configuration based on what is received from the peer.

  6. Enable the Data Center Bridging to accept the switch’s priority setting for FCoE.

    tux > sudo dcbtool sc eth2 app:fcoe e:1
      Version:       2
      Command:       Set Config
      Feature:       Application FCoE
      Port:          eth2
      Status:        Successful
  7. Copy the default FCoE configuration file to /etc/fcoe/cfg-eth2.

    sudo cp /etc/fcoe/cfg-ethx /etc/fcoe/cfg-eth2
  8. Start the FCoE Initiator service.

    systemctl start fcoe.service
  9. Set up the Link Layer Discovery Protocol agent daemon (llpad) and the FCoE Initiator service to start when booting.

    systemctl enable llpad fcoe

15.5 Managing FCoE Instances with the FCoE Administration Tool

The fcoeadm utility is the Fibre Channel over Ethernet (FCoE) management tool. It can be used to create, destroy, and reset an FCoE instance on a given network interface. The fcoeadm utility sends commands to a running fcoemon process via a socket interface. For information about fcoemon, see the man 8 fcoemon.

The fcoeadm utility allows you to query the FCoE instances about the following:

  • Interfaces

  • Target LUNs

  • Port statistics

The fcoeadm utility is part of the fcoe-utils package. The general syntax for the command looks like the following:

fcoeadm
  [-c|--create] [<ethX>]
  [-d|--destroy] [<ethX>]
  [-r|--reset] [<ethX>]
  [-S|--Scan] [<ethX>]
  [-i|--interface] [<ethX>]
  [-t|--target] [<ethX>]
  [-l|--lun] [<ethX>]
  [-s|--stats <ethX>] [<interval>]
  [-v|--version]
  [-h|--help]

Refer to man 8 fcoeadm for details.

Examples

fcoeadm -c eth2.101

Create an FCoE instance on eth2.101.

fcoeadm -d eth2.101

Destroy an FCoE instance on eth2.101.

fcoeadm -i eth3

Show information about all of the FCoE instances on interface eth3. If no interface is specified, information for all interfaces that have FCoE instances created will be shown. The following example shows information on connection eth0.201:

tux > sudo fcoeadm -i eth0.201
  Description:      82599EB 10-Gigabit SFI/SFP+ Network Connection
  Revision:         01
  Manufacturer:     Intel Corporation
  Serial Number:    001B219B258C
  Driver:           ixgbe 3.3.8-k2
  Number of Ports:  1

      Symbolic Name:     fcoe v0.1 over eth0.201
      OS Device Name:    host8
      Node Name:         0x1000001B219B258E
      Port Name:         0x2000001B219B258E
      FabricName:        0x2001000573D38141
      Speed:             10 Gbit
      Supported Speed:   10 Gbit
      MaxFrameSize:      2112
      FC-ID (Port ID):   0x790003
      State:             Online
fcoeadm -l eth3.101

Show detailed information about all of the LUNs discovered on connection eth3.101. If no connection is specified, information about all of the LUNs discovered on all FCoE connections will be shown.

fcoeadm -r eth2.101

Reset the FCoE instance on eth2.101.

fcoeadm -s eth3 3

Show statistical information about a specific eth3 port that has FCoE instances, at an interval of three seconds. The statistics are displayed one line per time interval. If no interval is given, the default of one second is used.

fcoeadm -t eth3

Show information about all of the discovered targets from a given eth3 port having FCoE instances. After each discovered target, any associated LUNs are listed. If no instance is specified, targets from all of the ports that have FCoE instances are shown. The following example shows information of targets from the eth0.201 connection:

tux > sudo fcoeadm -t eth0.201
  Interface:        eth0.201
  Roles:            FCP Target
  Node Name:        0x200000D0231B5C72
  Port Name:        0x210000D0231B5C72
  Target ID:        0
  MaxFrameSize:     2048
  OS Device Name:   rport-8:0-7
  FC-ID (Port ID):  0x79000C
  State:            Online

LUN ID  Device Name   Capacity   Block Size  Description
------  -----------  ----------  ----------  ----------------------------
    40  /dev/sdqi     792.84 GB      512     IFT DS S24F-R2840-4 (rev 386C)
    72  /dev/sdpk     650.00 GB      512     IFT DS S24F-R2840-4 (rev 386C)
   168  /dev/sdgy       1.30 TB      512     IFT DS S24F-R2840-4 (rev 386C)

15.6 Additional Information

For information, see the follow documentation:

  • For information about the Open-FCoE service daemon, see the fcoemon(8) man page.

  • For information about the Open-FCoE Administration tool, see the fcoeadm(8) man page.

  • For information about the Data Center Bridging Configuration tool, see the dcbtool(8) man page.

  • For information about the Link Layer Discovery Protocol agent daemon, see the lldpad(8) man page.

  • For general information, see the Open-FCoE home page: http://www.open-fcoe.org/dokuwiki/start.

16 NVMe over Fabric

  • Filename: storage_nvmeof.xml
  • ID: cha.nvmeof
Abstract

This chapter describes how to set up an NVMe over Fabric host and target.

16.1 Overview

NVM Express (NVMe) is an interface standard for accessing non-volatile storage, commonly SSD disks. NVMe supports much higher speeds and has a lower latency than SATA.

NVMe over Fabric is an architecture to access NVMe storage over different networking fabrics, for example RDMA or NVMe over Fibre Channel (FC-NVMe). The role of NVMe over Fabric is similar to iSCSI. To increase the fault-tolerance, NVMe over Fabric has a built-in support for multipathing. The NVMe over Fabric multipathing is not based on the traditional DM-Multipathing.

The NVMe host is the machine that connects to an NVMe target. The NVMe target is the machine that shares it's NVMe block devices.

NVMe is supported on SUSE Linux Enterprise Server 12 SP3. There are Kernel modules available for the NVMe block storage and NVMe over Fabric target and host.

To see if your hardware requires any special consideration, refer to Section 16.4, “Special Hardware Configuration”.

16.2 Setting Up an NVMe over Fabric Host

To use NVMe over Fabric, a target must be available with one of the supported networking methods. Supported are NVMe over Fibre Channel and RDMA. The following sections describe how to connect a host to a NVMe target.

16.2.1 Installing Command Line Client

To use NVMe over Fabric, you need the nvme command line tool. Install it with zypper:

tux > sudo zypper in nvme-cli

Use nvme --help to list all available subcommands. Man pages are available for nvme subcommands. Consult them by executing man nvme-SUBCOMMAND. For example, to view the man page for the discover subcommand, execute man nvme-discover.

16.2.2 Discovering NVMe over Fabric Targets

To list available NVMe subsystems on the NVMe over Fabric target, you need the discovery controller address and service ID.

tux > sudo nvme discover -t TRANSPORT -a DISCOVERY_CONTROLLER_ADDRESS -s SERVICE_ID

Replace TRANSPORT with the underlying transport medium: loop, rdma or fc. Replace DISCOVERY_CONTROLLER_ADDRESS with the address of the discovery controller. For RDMA this should be an IPv4 address. Replace SERVICE_ID with the transport service ID. If the service is IP based, like RDMA, service ID specifies the port number. For Fibre Channel, the service ID is not required.

The NVMe hosts only see the subsystems they are allowed to connect to.

Example:

tux > sudo nvme discover -t rdma -a 10.0.0.1 -s 4420

For more details, see man nvme-discover.

16.2.3 Connecting to NVMe over Fabric Targets

After you have identified the NVMe subsystem, you can connect it with the nvme connect command.

tux > sudo nvme connect -t transport -a DISCOVERY_CONTROLLER_ADDRESS -s SERVICE_ID -n SUBSYSTTEM_NQN

Replace TRANSPORT with the underlying transport medium: loop, rdma or fc. Replace DISCOVERY_CONTROLLER_ADDRESS with the address of the discovery controller. For RDMA this should be an IPv4 address. Replace SERVICE_ID with the transport service ID. If the service is IP based, like RDMA, this specifies the port number. Replace SUBSYSTTEM_NQN with the NVMe qualified name of the desired subsystem as found by the discovery command. NQN is the abbreviation for NVMe Qualified Name. The NQN must be unique.

Example:

tux > sudo nvme connect -t rdma -a 10.0.0.1 -s 4420 -n nqn.2014-08.com.example:nvme:nvm-subsystem-sn-d78432

Alternatively, use nvme connect-all to connect to all discovered namespaces. For advanced usage please see man nvme-connect and man nvme-connect-all.

16.2.4 Multipathing

NVMe native multipathing is enabled by default. To print the layout of the multipath devices, use the command nvme list-subsys. To disable NVMe native multipathing, add nvme-core.multipath=N as a boot parameter.

16.3 Setting Up an NVMe over Fabric Target

16.3.1 Installing Command Line Client

To configure a NVMe over Fabric target, you need the nvmetcli command line tool. Install it with zypper:

tux > sudo zypper in nvmetcli

The current documentation for nvmetcli is available at http://git.infradead.org/users/hch/nvmetcli.git/blob_plain/HEAD:/Documentation/nvmetcli.txt

16.3.2 Configuration Steps

The following procedure provides an example how to set up an NVMe over Fabric target.

The configuration is stored in a tree structure. Use the command cd to navigate. Use ls to list objects. You can create new objects with create.

  1. Start the nvmectli interactive shell.

    tux > sudo nvmetcli
  2. Create a new port.

    (nvmetcli)> cd ports
    (nvmetcli)> create 1
    (nvmetcli)> ls 1/
    o- 1
      o- referrals
      o- subsystems
  3. Create an NVMe subsystem.

    (nvmetcli)> cd /subsystems
    (nvmetcli)> create nqn.2014-08.org.nvmexpress:NVMf:uuid:c36f2c23-354d-416c-95de-f2b8ec353a82
    (nvmetcli)> cd nqn.2014-08.org.nvmexpress:NVMf:uuid:c36f2c23-354d-416c-95de-f2b8ec353a82/
    (nvmetcli)> ls
    o- nqn.2014-08.org.nvmexpress:NVMf:uuid:c36f2c23-354d-416c-95de-f2b8ec353a82
      o- allowed_hosts
      o- namespaces
  4. Create a new namespace and set an NVMe device to it.

    (nvmetcli)> cd namespaces
    (nvmetcli)> create 1
    (nvmetcli)> cd 1
    (nvmetcli)> set device path=/dev/nvme0n1
    Parameter path is now '/dev/nvme0n1'.
  5. Enable the previously created namespace.

    (nvmetcli)> cd ..
    (nvmetcli)> enable
    The Namespace has been enabled.
  6. Display the created namespace.

    (nvmetcli)> cd ..
    (nvmetcli)> ls
    o- nqn.2014-08.org.nvmexpress:NVMf:uuid:c36f2c23-354d-416c-95de-f2b8ec353a82
      o- allowed_hosts
      o- namespaces
        o- 1
  7. Allow all hosts to use the subsystem. Only do this in secure environments.

    (nvmetcli)> set attr allow_any_host=1
    Parameter allow_any_host is now '1'.

    Alternatively, you can allow only specific hosts to connect:

    (nvmetcli)> cd nqn.2014-08.org.nvmexpress:NVMf:uuid:c36f2c23-354d-416c-95de-f2b8ec353a82/allowed_hosts/
    (nvmetcli)> create hostnqn
  8. List all created objects:

    (nvmetcli)> cd /
    (nvmetcli)> ls
    o- /
      o- hosts
      o- ports
      | o- 1
      |   o- referrals
      |   o- subsystems
      o- subsystems
        o- nqn.2014-08.org.nvmexpress:NVMf:uuid:c36f2c23-354d-416c-95de-f2b8ec353a82
          o- allowed_hosts
          o- namespaces
            o- 1
  9. Make the target available via RDMA:

    (nvmetcli)> cd ports/1/
    (nvmetcli)> set addr adrfam=ipv4 trtype=rdma traddr=10.0.0.1 trsvcid=4420
    Parameter trtype is now 'rdma'.
    Parameter adrfam is now 'ipv4'.
    Parameter trsvcid is now '4420'.
    Parameter traddr is now '10.0.0.1'.

    Alternatively, you can make it available with Fibre Channel:

    (nvmetcli)> cd ports/1/
    (nvmetcli)> set addr adrfam=fc trtype=fc traddr=nn-0x1000000044001123:pn-0x2000000055001123 trsvcid=none

16.3.3 Back Up and Restore Target Configuration

You can save the target configuration in a JSON file with the following commands:

tux > sudo nvmetcli
(nvmetcli)> saveconfig nvme-target-backup.json

To restore the configuration, use:

(nvmetcli)> restore nvme-target-backup.json

You can also wipe the current configuration:

(nvmetcli)> clear

16.4 Special Hardware Configuration

16.4.1 Overview

Some hardware needs special configuration to work correctly. Skim the titles of the following sections to see if you are using any of the mentioned devices or vendors.

16.4.2 Broadcom

If you are using the Broadcom Emulex LightPulse Fibre Channel SCSI driver, add a Kernel configuration parameter on the target and host for the lpfc module:

tux > sudo echo "options lpfc lpfc_enable_fc4_type=3" > /etc/modprobe.d/lpfc.conf

Make sure that the Broadcom adapter firmware has at least version 11.2.156.27. Also make sure that you have the current versions of nvme-cli, nvmetlci and the Kernel installed.

To enable a Fibre Channel port as an NVMe target, set a module parameter lpfc_enable_nvmet= COMMA_SEPARATED_WWPNS. Only listed WWPNs will be configured for target mode. A Fibre Channel port can either be configured as target or as initiator.

For more details, also refer to https://docs.broadcom.com/docs/12379413.

16.5 More Information

For more details about the abilities of nvme, refer to nvme nvme-help.

The following links provide a basic introduction to NVMe and NVMe over Fabric:

17 Managing Multipath I/O for Devices

  • Filename: storage_multipath.xml
  • ID: cha.multipath

This section describes how to manage failover and path load balancing for multiple paths between the servers and block storage devices by using Multipath I/O (MPIO).

17.1 Understanding Multipath I/O

Multipathing is the ability of a server to communicate with the same physical or logical block storage device across multiple physical paths between the host bus adapters in the server and the storage controllers for the device, typically in Fibre Channel (FC) or iSCSI SAN environments. You can also achieve multiple connections with direct attached storage when multiple channels are available.

Linux multipathing provides connection fault tolerance and can provide load balancing across the active connections. When multipathing is configured and running, it automatically isolates and identifies device connection failures, and reroutes I/O to alternate connections.

Typical connection problems involve faulty adapters, cables, or controllers. When you configure multipath I/O for a device, the multipath driver monitors the active connection between devices. When the multipath driver detects I/O errors for an active path, it fails over the traffic to the device’s designated secondary path. When the preferred path becomes healthy again, control can be returned to the preferred path.

17.2 Hardware Support

The multipathing drivers and tools support all architectures for which SUSE Linux Enterprise Server is available. They support most storage arrays. The storage array that houses the multipathed device must support multipathing to use the multipathing drivers and tools. Some storage array vendors provide their own multipathing management tools. Consult the vendor’s hardware documentation to determine what settings are required.

17.2.1 Storage Arrays That Are Automatically Detected for Multipathing

The multipath-tools package automatically detects the following storage arrays:

3PARdata VV
AIX NVDISK
AIX VDASD
APPLE Xserve RAID
COMPELNT Compellent Vol
COMPAQ/HP HSV101, HSV111, HSV200, HSV210, HSV300, HSV400, HSV 450
COMPAQ/HP MSA, HSV
COMPAQ/HP MSA VOLUME
DataCore SANmelody
DDN SAN DataDirector
DEC HSG80
DELL MD3000
DELL MD3000i
DELL MD32xx
DELL MD32xxi
DGC
EMC Clariion
EMC Invista
EMC SYMMETRIX
EUROLOGC FC2502
FSC CentricStor
FUJITSU ETERNUS_DX, DXL, DX400, DX8000
HITACHI DF
HITACHI/HP OPEN
HP A6189A
HP HSVX700
HP LOGICAL VOLUME
HP MSA2012fc, MSA 2212fc, MSA2012i
HP MSA2012sa, MSA2312 fc/i/sa, MCA2324 fc/i/sa, MSA2000s VOLUME
HP P2000 G3 FC|P2000G3 FC/iSCSI|P2000 G3 SAS|P2000 G3 iSCSI
IBM 1722-600
IBM 1724
IBM 1726
IBM 1742
IBM 1745, 1746
IBM 1750500
IBM 1814
IBM 1815
IBM 1818
IBM 1820N00
IBM 2105800
IBM 2105F20
IBM 2107900
IBM 2145
IBM 2810XIV
IBM 3303 NVDISK
IBM 3526
IBM 3542
IBM IPR
IBM Nseries
IBM ProFibre 4000R
IBM S/390 DASD ECKD
IBM S/390 DASD FBA
Intel Multi-Flex
LSI/ENGENIO INF-01-00
NEC DISK ARRAY
NETAPP LUN
NEXENTA COMSTAR
Pillar Axiom
PIVOT3 RAIGE VOLUME
SGI IS
SGI TP9100, TP 9300
SGI TP9400, TP9500
STK FLEXLINE 380
STK OPENstorage D280
SUN CSM200_R
SUN LCSM100_[IEFS]
SUN STK6580, STK6780
SUN StorEdge 3510, T4
SUN SUN_6180

In general, most other storage arrays should work. When storage arrays are automatically detected, the default settings for multipathing apply. If you want non-default settings, you must manually create and configure the /etc/multipath.conf file. The same applies for hardware that is not automatically detected. For information, see Section 17.6, “Creating or Modifying the /etc/multipath.conf File”.

Consider the following caveats:

17.2.2 Tested Storage Arrays for Multipathing Support

Storage arrays from the following vendors have been tested with SUSE Linux Enterprise Server:

EMC
Hitachi
Hewlett-Packard/Compaq
IBM
NetApp
SGI

Most other vendor storage arrays should also work. Consult your vendor’s documentation for guidance. For a list of the default storage arrays recognized by the multipath-tools package, see Section 17.2.1, “Storage Arrays That Are Automatically Detected for Multipathing”.

17.2.3 Storage Arrays that Require Specific Hardware Handlers

Storage arrays that require special commands on failover from one path to the other or that require special nonstandard error handling might require more extensive support. Therefore, the Device Mapper Multipath service has hooks for hardware handlers. For example, one such handler for the EMC CLARiiON CX family of arrays is already provided.

Important
Important: For More Information

Consult the hardware vendor’s documentation to determine if its hardware handler must be installed for Device Mapper Multipath.

The multipath -t command shows an internal table of storage arrays that require special handling with specific hardware handlers. The displayed list is not an exhaustive list of supported storage arrays. It lists only those arrays that require special handling and that the multipath-tools developers had access to during the tool development.

Important
Important: Exceptions

Arrays with true active/active multipath support do not require special handling, so they are not listed for the multipath -t command.

A listing in the multipath -t table does not necessarily mean that SUSE Linux Enterprise Server was tested on that specific hardware. For a list of tested storage arrays, see Section 17.2.2, “Tested Storage Arrays for Multipathing Support”.

17.3 Planning for Multipathing

Use the guidelines in this section when planning your multipath I/O solution.

17.3.1 Prerequisites

  • Multipathing is managed at the device level.

  • The storage array you use for the multipathed device must support multipathing. For more information, see Section 17.2, “Hardware Support”.

  • You need to configure multipathing only if multiple physical paths exist between host bus adapters in the server and host bus controllers for the block storage device. You configure multipathing for the logical device as seen by the server.

  • For some storage arrays, the vendor provides its own multipathing software to manage multipathing for the array’s physical and logical devices. In this case, you should follow the vendor’s instructions for configuring multipathing for those devices.

  • When using multipathing in a virtualization environment, the multipathing is controlled in the host server environment. Configure multipathing for the device before you assign it to a virtual guest machine.

17.3.2 Disk Management Tasks

Perform the following disk management tasks before you attempt to configure multipathing for a physical or logical device that has multiple paths:

  • Use third-party tools to carve physical disks into smaller logical disks.

  • Use third-party tools to partition physical or logical disks. If you change the partitioning in the running system, the Device Mapper Multipath (DM-MP) module does not automatically detect and reflect these changes. DM-MPIO must be re-initialized, which usually requires a reboot.

  • Use third-party SAN array management tools to create and configure hardware RAID devices.

  • Use third-party SAN array management tools to create logical devices such as LUNs. Logical device types that are supported for a given array depend on the array vendor.

17.3.3 Software RAIDs

The Linux software RAID management software runs on top of multipathing. For each device that has multiple I/O paths and that you plan to use in a software RAID, you must configure the device for multipathing before you attempt to create the software RAID device. Automatic discovery of multipathed devices is not available. The software RAID is not aware of the multipathing management running underneath.

For information about setting up multipathing for existing software RAIDs, see Section 17.12, “Configuring Multipath I/O for an Existing Software RAID”.

17.3.4 High-Availability Solutions

High-availability solutions for clustering storage resources run on top of the multipathing service on each node. Make sure that the configuration settings in the /etc/multipath.conf file on each node are consistent across the cluster.

Make sure that multipath devices have the same name across all devices. Refer to Section 17.9.1, “Multipath Device Names in HA Clusters” for details.

The Distributed Replicated Block Device (DRBD) high-availability solution for mirroring devices across a LAN runs on top of multipathing. For each device that has multiple I/O paths and that you plan to use in a DRDB solution, you must configure the device for multipathing before you configure DRBD.

17.3.5 Always Keep the initrd in Synchronization with the System Configuration

One of the most important requirements when using Multipath is to make sure that the initrd and the installed system behave the same regarding the root file system and all other file systems required to boot the system. If Multipath is enabled in the system, it also needs to be enabled in the initrd and vice versa. See Section 17.5.1, “Enabling, Disabling, Starting and Stopping Multipath I/O Services” for details.

If the initrd and the system are not synchronized, the system will not properly boot and the start-up procedure will result in an emergency shell. See Section 17.15.1, “The System Exits to Emergency Shell at Boot When Multipath Is Enabled” for instructions on how to avoid or repair such a scenario.

17.4 Multipath Management Tools

The multipathing support in SUSE Linux Enterprise Server is based on the Device Mapper Multipath module of the Linux kernel and the multipath-tools user space package. You can use the Multiple Devices Administration utility (multipath) to view the status of multipathed devices.

17.4.1 Device Mapper Multipath Module

The Device Mapper Multipath (DM-MP) module provides the multipathing capability for Linux. DM-MPIO is the preferred solution for multipathing on SUSE Linux Enterprise Server. It is the only multipathing option shipped with the product that is completely supported by SUSE.

DM-MPIO features automatic configuration of the multipathing subsystem for a large variety of setups. Configurations of up to eight paths to each device are supported. Configurations are supported for active/passive (one path active, others passive) or active/active (all paths active with round-robin load balancing).

The DM-MPIO framework is extensible in two ways:

The user space component of DM-MPIO takes care of automatic path discovery and grouping, and automated path retesting, so that a previously failed path is automatically reinstated when it becomes healthy again. This minimizes the need for administrator attention in a production environment.

DM-MPIO protects against failures in the paths to the device, and not failures in the device itself. If one of the active paths is lost (for example, a network adapter breaks or a fiber-optic cable is removed), I/O is redirected to the remaining paths. If the configuration is active/passive, then the path fails over to one of the passive paths. If you are using the round-robin load-balancing configuration, the traffic is balanced across the remaining healthy paths. If all active paths fail, inactive secondary paths must be woken up, so failover occurs with a delay of approximately 30 seconds.

If a disk array has more than one storage processor, ensure that the SAN switch has a connection to the storage processor that owns the LUNs you want to access. On most disk arrays, all LUNs belong to both storage processors, so both connections are active.

Note
Note: Storage Processors

On some disk arrays, the storage array manages the traffic through storage processors so that it presents only one storage processor at a time. One processor is active and the other one is passive until there is a failure. If you are connected to the wrong storage processor (the one with the passive path) you might not see the expected LUNs, or you might see the LUNs but get errors when you try to access them.

Table 17.1: Multipath I/O Features of Storage Arrays

Features of Storage Arrays

Description

Active/passive controllers

One controller is active and serves all LUNs. The second controller acts as a standby. The second controller also presents the LUNs to the multipath component so that the operating system knows about redundant paths. If the primary controller fails, the second controller takes over, and it serves all LUNs.

In some arrays, the LUNs can be assigned to different controllers. A given LUN is assigned to one controller to be its active controller. One controller does the disk I/O for any LUN at a time, and the second controller is the standby for that LUN. The second controller also presents the paths, but disk I/O is not possible. Servers that use that LUN are connected to the LUN’s assigned controller. If the primary controller for a set of LUNs fails, the second controller takes over, and it serves all LUNs.

Active/active controllers

Both controllers share the load for all LUNs, and can process disk I/O for any LUN. If one controller fails, the second controller automatically handles all traffic.

Load balancing

The Device Mapper Multipath driver automatically load balances traffic across all active paths.

Controller failover

When the active controller fails over to the passive, or standby, controller, the Device Mapper Multipath driver automatically activates the paths between the host and the standby, making them the primary paths.

Boot/Root device support

Multipathing is supported for the root (/) device in SUSE Linux Enterprise Server 10 and later. The host server must be connected to the currently active controller and storage processor for the boot device.

Multipathing is supported for the /boot device in SUSE Linux Enterprise Server 11 and later.

Device Mapper Multipath detects every path for a multipathed device as a separate SCSI device. The SCSI device names take the form /dev/sdN, where N is an autogenerated letter for the device, beginning with a and issued sequentially as the devices are created, such as /dev/sda, /dev/sdb, and so on. If the number of devices exceeds 26, the letters are duplicated so that the next device after /dev/sdz will be named /dev/sdaa, /dev/sdab, and so on.

If multiple paths are not automatically detected, you can configure them manually in the /etc/multipath.conf file. The multipath.conf file does not exist until you create and configure it. For information, see Section 17.6, “Creating or Modifying the /etc/multipath.conf File”.

17.4.2 Multipath I/O Management Tools

The packages multipath-tools and kpartx provide tools that take care of automatic path discovery and grouping. They automatically test the path periodically, so that a previously failed path is automatically reinstated when it becomes healthy again. This minimizes the need for administrator attention in a production environment.

Table 17.2: Tools in the multipath-tools Package

Tool

Description

multipath

Scans the system for multipathed devices and assembles them.

multipathd

Waits for maps events, then executes multipath.

kpartx

Maps linear devmaps to partitions on the multipathed device, which makes it possible to create multipath monitoring for partitions on the device.

mpathpersist

Manages SCSI-persistent reservations on Device Mapper Multipath devices.ppc

17.4.3 Using MDADM for Multipathed Devices

Udev is the default device handler, and devices are automatically known to the system by the Worldwide ID instead of by the device node name. This resolves problems in previous releases of MDADM and LVM where the configuration files (mdadm.conf and lvm.conf) did not properly recognize multipathed devices.

As with LVM2, MDADM requires that the devices be accessed by the ID rather than by the device node path. Therefore, the DEVICE entry in /etc/mdadm.conf should be set as follows:

DEVICE /dev/disk/by-id/*

If you are using user-friendly names, specify the path as follows so that only the device mapper names are scanned after multipathing is configured:

DEVICE /dev/disk/by-id/dm-uuid-.*-mpath-.*

17.4.4 The multipath Command

Use the Linux multipath(8) command to configure and manage multipathed devices. The general syntax for the command looks like the following:

multipath [-v verbosity_level] [-b bindings_file] [-d] [-h|-l|-ll|-f|-F|-B|-c|-q|-r|-w|-W|-t] [-p failover|multibus|group_by_serial|group_by_prio|group_by_node_name] [DEVICENAME]

Refer to man 8 multipath for details.

General Examples

multipath

Configures all multipath devices.

multipath DEVICENAME

Configures a specific multipath device.

Replace DEVICENAME with the device node name such as /dev/sdb (as shown by udev in the $DEVNAME variable), or in the major:minor format. The device may alternatively be a multipath map name.

multipath -f

Selectively suppresses a multipath map, and its device-mapped partitions.

multipath -d

Dry run. Displays potential multipath devices, but does not create any devices and does not update device maps.

multipath -v2 -d

Displays multipath map information for potential multipath devices in a dry run. The -v2 option shows only local disks. This verbosity level prints the created or updated multipath names only for use to feed other tools like kpartx.

There is no output if the device already exists and there are no changes. Use multipath -ll to see the status of configured multipath devices.

multipath -v2 DEVICENAME

Configures a specific potential multipath device and displays multipath map information for it. This verbosity level prints only the created or updated multipath names for use to feed other tools like kpartx.

There is no output if the device already exists and there are no changes. Use multipath -ll to see the status of configured multipath devices.

Replace DEVICENAME with the device node name such as /dev/sdb (as shown by udev in the $DEVNAME variable), or in the major:minor format. The device may alternatively be a multipath map name.

multipath -v3

Configures potential multipath devices and displays multipath map information for them. This verbosity level prints all detected paths, multipaths, and device maps. Both WWID and devnode blacklisted devices are displayed.

multipath -v3 DEVICENAME

Configures a specific potential multipath device and displays information for it. The -v3 option shows the full path list. This verbosity level prints all detected paths, multipaths, and device maps. Both WWID and devnode blacklisted devices are displayed.

Replace DEVICENAME with the device node name such as /dev/sdb (as shown by udev in the $DEVNAME variable), or in the major:minor format. The device may alternatively be a multipath map name.

multipath -ll

Displays the status of all multipath devices.

multipath -ll DEVICENAME

Displays the status of a specified multipath device.

Replace DEVICENAME with the device node name such as /dev/sdb (as shown by udev in the $DEVNAME variable), or in the major:minor format. The device may alternatively be a multipath map name.

multipath -F

Flushes all unused multipath device maps. This unresolves the multiple paths; it does not delete the devices.

multipath -F DEVICENAME

Flushes unused multipath device maps for a specified multipath device. This unresolves the multiple paths; it does not delete the device.

Replace DEVICENAME with the device node name such as /dev/sdb (as shown by udev in the $DEVNAME variable), or in the major:minor format. The device may alternatively be a multipath map name.

multipath -p [ failover | multibus | group_by_serial | group_by_prio | group_by_node_name ]

Sets the group policy by specifying one of the group policy options that are described in the following table:

Table 17.3: Group Policy Options for the multipath -p Command

Policy Option

Description

failover

(Default) One path per priority group. You can use only one path at a time.

multibus

All paths in one priority group.

group_by_serial

One priority group per detected SCSI serial number (the controller node worldwide number).

group_by_prio

One priority group per path priority value. Paths with the same priority are in the same priority group. Priorities are determined by callout programs specified as a global, per-controller, or per-multipath option in the /etc/multipath.conf configuration file.

group_by_node_name

One priority group per target node name. Target node names are fetched in the /sys/class/fc_transport/target*/node_name location.

multipath -t

Shows internal hardware table and active configuration of multipath. Refer to man multipath for details about the configuration parameters.

17.4.5 The mpathpersist Utility

The mpathpersist utility can be used to manage SCSI persistent reservations on Device Mapper Multipath devices. The general syntax for the command looks like the following:

mpathpersist [options] [device]

Refer to man 8 mpathpersist for details.

Use this utility with the service action reservation key (reservation_key attribute) in the /etc/multipath.conf file to set persistent reservations for SCSI devices. The attribute is not used by default. If it is not set, the multipathd daemon does not check for persistent reservation for newly discovered paths or reinstated paths.

reservation_key <RESERVATION_KEY>

You can add the attribute to the defaults section or the multipaths section. For example:

multipaths {
  multipath {
    wwid   XXXXXXXXXXXXXXXX
    alias      yellow
    reservation_key  0x123abc
  }
}

Set the reservation_key parameter for all mpath devices applicable for persistent management, then restart the multipathd daemon by running the following command:

sudo systemctl restart multipathd

After it is set up, you can specify the reservation key in the mpathpersist commands.

Examples

mpathpersist --out --register --param-sark=123abc --prout-type=5 -d /dev/mapper/mpath9

Register the Service Action Reservation Key for the /dev/mapper/mpath9 device.

mpathpersist -i -k -d /dev/mapper/mpath9

Read the Service Action Reservation Key for the /dev/mapper/mpath9 device.

mpathpersist --out --reserve --param-sark=123abc --prout-type=8 -d /dev/mapper/mpath9

Reserve the Service Action Reservation Key for the /dev/mapper/mpath9 device.

mpathpersist -i -s -d /dev/mapper/mpath9

Read the reservation status of the /dev/mapper/mpath9 device.

17.5 Configuring the System for Multipathing

17.5.1 Enabling, Disabling, Starting and Stopping Multipath I/O Services

To enable multipath services to start at boot time, run the following command:

sudo systemctl enable multipathd

To manually start the service in the running system or to check its status, enter one of the following commands:

sudo systemctl start multipathd
sudo systemctl status multipathd

To stop the multipath services in the current session and to disable it, so it will not be started the next time the system is booted, run the following commands:

sudo systemctl stop multipathd
sudo systemctl disable multipathd
Important
Important: Rebuilding the initrd

Whenever you enable or disable the multipath services it is also required to rebuild the initrd, otherwise the system may not boot anymore. When enabling the multipath services, also run the following command to rebuild the initrd:

dracut --force --add multipath

When disabling the services, then run the following command to rebuild the initrd:

dracut --force -o multipath

Additionally and optionally, if you also want to make sure multipath devices do not get set up, even when starting multipath manually, add the following lines to the end of /etc/multipath.conf before rebuilding the initrd:

blacklist {
    wwid ".*"
}

17.5.2 Preparing SAN Devices for Multipathing

Before configuring multipath I/O for your SAN devices, prepare the SAN devices, as necessary, by doing the following:

  • Configure and zone the SAN with the vendor’s tools.

  • Configure permissions for host LUNs on the storage arrays with the vendor’s tools.

  • Install the Linux HBA driver module. Upon module installation, the driver automatically scans the HBA to discover any SAN devices that have permissions for the host. It presents them to the host for further configuration.

    Note
    Note: No Native Multipathing

    Make sure that the HBA driver you are using does not have native multipathing enabled.

    See the vendor’s specific instructions for more details.

  • After the driver module is loaded, discover the device nodes assigned to specific array LUNs or partitions.

  • If the SAN device will be used as the root device on the server, modify the timeout settings for the device as described in Section 17.14.9, “SAN Timeout Settings When the Root Device Is Multipathed”.

If the LUNs are not seen by the HBA driver, lsscsi can be used to check whether the SCSI devices are seen correctly by the operating system. When the LUNs are not seen by the HBA driver, check the zoning setup of the SAN. In particular, check whether LUN masking is active and whether the LUNs are correctly assigned to the server.

If the LUNs are seen by the HBA driver, but there are no corresponding block devices, additional kernel parameters are needed to change the SCSI device scanning behavior, such as to indicate that LUNs are not numbered consecutively. For information, see TID 3955167: Troubleshooting SCSI (LUN) Scanning Issues in the SUSE Knowledgebase at https://www.suse.com/support/kb/doc.php?id=3955167.

17.5.3 Partitioning Multipath Devices

Partitioning devices that have multiple paths is not recommended, but it is supported. You can use the kpartx tool to create partitions on multipath devices without rebooting. You can also partition the device before you attempt to configure multipathing by using the Partitioner function in YaST, or by using a third-party partitioning tool.

Multipath devices are device-mapper devices. Modifying device-mapper devices with command line tools (such as parted, kpartx, or fdisk) works, but it does not necessarily generate the udev events that are required to update other layers. After you partition the device-mapper device, you should check the multipath map to make sure the device-mapper devices were mapped. If they are missing, you can remap the multipath devices or reboot the server to pick up all of the new partitions in the multipath map.

The device-mapper device for a partition on a multipath device is not the same as an independent device. When you create an LVM logical volume using the whole device, you must specify a device that contains no partitions. If you specify a multipath partition as the target device for the LVM logical volume, LVM recognizes that the underlying physical device is partitioned and the create fails. If you need to subdivide a SAN device, you can carve LUNs on the SAN device and present each LUN as a separate multipath device to the server.

17.6 Creating or Modifying the /etc/multipath.conf File

The /etc/multipath.conf file does not exist unless you create it. Default multipath device settings are applied automatically when the multipathd daemon runs unless you create the multipath configuration file and personalize the settings.

Important
Important: Testing and Permanently Applying Changes from /etc/multipath.conf

Whenever you create or modify the /etc/multipath.conf file, the changes are not automatically applied when you save the file. This allows you to perform a dry run to verify your changes before they are committed. When you are satisfied with the revised settings, you can update the multipath maps as described in Section 17.6.4, “Applying the /etc/multipath.conf File Changes to Update the Multipath Maps”.

17.6.1 Creating the /etc/multipath.conf File

  1. Create an empty /etc/multipath.conf file with an editor of your choice.

  2. Make sure to add an appropriate device section for your SAN. Most vendors provide documentation on the proper setup of the device section. Note that different SANs require individual device sections.

    If you are using a storage subsystem that is automatically detected (see Section 17.2.1, “Storage Arrays That Are Automatically Detected for Multipathing”), adding a device is not required—the default settings for this device will be applied in this case.

  3. Create a blacklist section containing all non-multipath devices of your machine. Refer to Section 17.8, “Blacklisting Non-Multipath Devices” for details.

  4. If required, add more sections to the configuration file. Refer to Section 17.6.2, “Sections in the /etc/multipath.conf File” for a brief introduction. More details are available when running man 5 multipath.conf.

  5. When finished, save /etc/multipath.conf and test your settings as described in Section 17.6.3, “Verifying the Multipath Setup in the /etc/multipath.conf File”.

  6. When you have successfully verified the configuration, apply it as described in Section 17.6.4, “Applying the /etc/multipath.conf File Changes to Update the Multipath Maps”.

17.6.2 Sections in the /etc/multipath.conf File

The /etc/multipath.conf file is organized into the following sections. See man 5 multipath.conf for details.

defaults

General default settings for multipath I/0. These values are used if no values are given in the appropriate device or multipath sections. For information, see Section 17.7, “Configuring Default Policies for Polling, Queuing, and Failback”.

blacklist

Lists the device names to discard as not multipath candidates. Devices can be identified by their device node name (devnode), their WWID (wwid), or their vendor or product strings (device). You can typically ignore non-multipathed devices, such as hpsa, fd, hd, md, dm, sr, scd, st, ram, raw, loop. For more information and examples, see Section 17.8, “Blacklisting Non-Multipath Devices”.

blacklist_exceptions

Lists the device names of devices to be treated as multipath candidates even if they are on the blacklist. Devices can be identified by their device node name (devnode), their WWID (wwid), or their vendor or product strings (device). You must specify the excepted devices by using the same keyword that you used in the blacklist. For example, if you used the devnode keyword for devices in the blacklist, you use the devnode keyword to exclude some devices in the blacklist exceptions. It is not possible to blacklist devices by using the devnode keyword and to exclude some of them by using the wwid keyword. For more information and examples, see Section 17.8, “Blacklisting Non-Multipath Devices”.

multipaths

Specifies settings for individual multipath devices. Except for settings that do not support individual settings, these values overwrite what is specified in the defaults and devices sections of the configuration file.

devices

Specifies settings for individual storage controllers. These values overwrite values specified in the defaults section of the configuration file. If you use a storage array that is not supported by default, you can create a devices subsection to specify the default settings for it. These values can be overwritten by settings for individual multipath devices if the keyword allows it.

For information, see the following:

17.6.3 Verifying the Multipath Setup in the /etc/multipath.conf File

Whenever you create or modify the /etc/multipath.conf file, the changes are not automatically applied when you save the file. You can perform a dry run of the setup to verify the multipath setup before you update the multipath maps.

At the server command prompt, enter

sudo multipath -v2 -d

This command scans the devices, then displays what the setup would look like if you commit the changes. It is assumed that the multipathd daemon is already running with the old (or default) multipath settings when you modify the /etc/multipath.conf file and perform the dry run. If the changes are acceptable, continue with the next step.

The output is similar to the following:

26353900f02796769
[size=127 GB]
[features="0"]
[hwhandler="1    emc"]

\_ round-robin 0 [first]
  \_ 1:0:1:2 sdav 66:240  [ready ]
  \_ 0:0:1:2 sdr  65:16   [ready ]

\_ round-robin 0
  \_ 1:0:0:2 sdag 66:0    [ready ]
  \_ 0:0:0:2 sdc   8:32   [ready ]

Paths are grouped into priority groups. Only one priority group is in active use at a time. To model an active/active configuration, all paths end in the same group. To model an active/passive configuration, the paths that should not be active in parallel are placed in several distinct priority groups. This normally happens automatically on device discovery.

The output shows the order, the scheduling policy used to balance I/O within the group, and the paths for each priority group. For each path, its physical address (host:bus:target:lun), device node name, major:minor number, and state is shown.

By using a verbosity level of -v3 in the dry run, you can see all detected paths, multipaths, and device maps. Both WWID and device node blacklisted devices are displayed.

The following is an example of -v3 output on a 64-bit SLES 11 SP2 server with two Qlogic HBAs connected to a Xiotech Magnitude 3000 SAN. Some multiple entries have been omitted to shorten the example.

tux > sudo multipath -v3 d
dm-22: device node name blacklisted
< content omitted >
loop7: device node name blacklisted
< content omitted >
md0: device node name blacklisted
< content omitted >
dm-0: device node name blacklisted
sdf: not found in pathvec
sdf: mask = 0x1f
sdf: dev_t = 8:80
sdf: size = 105005056
sdf: subsystem = scsi
sdf: vendor = XIOtech
sdf: product = Magnitude 3D
sdf: rev = 3.00
sdf: h:b:t:l = 1:0:0:2
sdf: tgt_node_name = 0x202100d0b2028da
sdf: serial = 000028DA0014
sdf: getuid= "/lib/udev/scsi_id --whitelisted --device=/dev/%n" (config file default)
sdf: uid = 200d0b2da28001400 (callout)
sdf: prio = const (config file default)
sdf: const prio = 1
[...]
ram15: device node name blacklisted
[...]
===== paths list =====
uuid              hcil    dev dev_t pri dm_st  chk_st  vend/prod/rev
200d0b2da28001400 1:0:0:2 sdf 8:80  1   [undef][undef] XIOtech,Magnitude 3D
200d0b2da28005400 1:0:0:1 sde 8:64  1   [undef][undef] XIOtech,Magnitude 3D
200d0b2da28004d00 1:0:0:0 sdd 8:48  1   [undef][undef] XIOtech,Magnitude 3D
200d0b2da28001400 0:0:0:2 sdc 8:32  1   [undef][undef] XIOtech,Magnitude 3D
200d0b2da28005400 0:0:0:1 sdb 8:16  1   [undef][undef] XIOtech,Magnitude 3D
200d0b2da28004d00 0:0:0:0 sda 8:0   1   [undef][undef] XIOtech,Magnitude 3D
params = 0 0 2 1 round-robin 0 1 1 8:80 1000 round-robin 0 1 1 8:32 1000
status = 2 0 0 0 2 1 A 0 1 0 8:80 A 0 E 0 1 0 8:32 A 0
sdf: mask = 0x4
sdf: path checker = directio (config file default)
directio: starting new request
directio: async io getevents returns 1 (errno=Success)
directio: io finished 4096/0
sdf: state = 2
[...]

17.6.4 Applying the /etc/multipath.conf File Changes to Update the Multipath Maps

Changes to the /etc/multipath.conf file cannot take effect when multipathd is running. After you make changes, save and close the file, then do the following to apply the changes and update the multipath maps:

  1. Stop the multipathd service:

    sudo systemctl stop multipathd
  2. Clear old multipath bindings by entering

    sudo /sbin/multipath -F
  3. Create new multipath bindings by entering

    sudo /sbin/multipath -v2 -l
  4. Restart the multipathd service:

    sudo systemctl start multipathd
  5. Run dracut -f to re-create the initrd image on your system, then reboot for the changes to take effect.

17.6.5 Generating a WWID

To identify a device over different paths, multipath uses a World Wide Identification (WWID) for each device. If the WWID is the same for two device paths, they are assumed to represent the same device. We recommend not changing the method of WWID generation, unless there is a compelling reason to do so. For more details, see man multipath.conf.

17.7 Configuring Default Policies for Polling, Queuing, and Failback

The goal of multipath I/O is to provide connectivity fault tolerance between the storage system and the server. The desired default behavior depends on whether the server is a stand-alone server or a node in a high-availability cluster.

When you configure multipath I/O for a stand-alone server, the no_path_retry setting protects the server operating system from receiving I/O errors as long as possible. It queues messages until a multipath failover occurs and provides a healthy connection.

When you configure multipath I/O for a node in a high-availability cluster, you want multipath to report the I/O failure to trigger the resource failover instead of waiting for a multipath failover to be resolved. In cluster environments, you must modify the no_path_retry setting so that the cluster node receives an I/O error in relation to the cluster verification process (recommended to be 50% of the heartbeat tolerance) if the connection is lost to the storage system. In addition, you want the multipath I/O fallback to be set to manual to avoid a ping-pong of resources because of path failures.

The /etc/multipath.conf file should contain a defaults section where you can specify default behaviors for polling, queuing, and failback. If the field is not otherwise specified in a device section, the default setting is applied for that SAN configuration.

The following are the compiled default settings. They will be used unless you overwrite these values by creating and configuring a personalized /etc/multipath.conf file.

defaults {
  verbosity 2
#  udev_dir is deprecated in SLES 11 SP3
#  udev_dir              /dev
  polling_interval      5
#  path_selector default value is service-time in SLES 11 SP3
#  path_selector         "round-robin 0"
  path selector         "service-time 0"
  path_grouping_policy  failover
#  getuid_callout is deprecated in SLES 11 SP3 and replaced with uid_attribute
#  getuid_callout        "/lib/udev/scsi_id --whitelisted --device=/dev/%n"
#  uid_attribute is new in SLES 11 SP3
  uid_attribute         "ID_SERIAL"
  prio                  "const"
  prio_args             ""
  features              "0"
  path_checker          "tur"
  alias_prefix          "mpath"
  rr_min_io_rq          1
  max_fds               "max"
  rr_weight             "uniform"
  queue_without_daemon  "yes"
  flush_on_last_del     "no"
  user_friendly_names   "no"
  fast_io_fail_tmo      5
  bindings_file         "/etc/multipath/bindings"
  wwids_file            "/etc/multipath/wwids"
  log_checker_err       "always"

  retain_attached_hw_handler  "no"
  detect_prio           "no"
  failback              "manual"
  no_path_retry         "fail"
  }

For information about setting the polling, queuing, and failback policies, see the following parameters in Section 17.10, “Configuring Path Failover Policies and Priorities”:

After you have modified the /etc/multipath.conf file, you must run dracut -f to re-create the initrd on your system, then restart the server for the changes to take effect. See Section 17.6.4, “Applying the /etc/multipath.conf File Changes to Update the Multipath Maps” for details.

17.8 Blacklisting Non-Multipath Devices

The /etc/multipath.conf file can contain a blacklist section where all non-multipath devices are listed. You can blacklist devices by WWID (wwid keyword), device name (devnode keyword), or device type (device section). You can also use the blacklist_exceptions section to enable multipath for some devices that are blacklisted by the regular expressions used in the blacklist section.

Note
Note: Preferred Blacklisting Methods

The preferred method for blacklisting devices is by WWID or by vendor and product. Blacklisting by devnode is not recommended, because device nodes can change and thus are not useful for persistent device identification.

Warning
Warning: Regular Expressions in multipath.conf

Regular expressions in the /etc/multipath.conf do not work in general. They only work if they are matched against common strings. However, the standard configuration of multipath already contains regular expressions for many devices and vendors. Matching regular expressions with other regular expressions does not work. Make sure that you are only matching against strings shown with multipath -t.

You can typically ignore non-multipathed devices, such as hpsa, fd, hd, md, dm, sr, scd, st, ram, raw, and loop. For example, local SATA hard disks and flash disks do not have multiple paths. If you want multipath to ignore single-path devices, put them in the blacklist section.

Note
Note: Compatibility

The keyword devnode_blacklist has been deprecated and replaced with the keyword blacklist.

With SUSE Linux Enterprise Server 12 the glibc-provided regular expressions are used. To match an arbitrary string, you must now use ".*" rather than "*".

For example, to blacklist local devices and all arrays from the hpsa driver from being managed by multipath, the blacklist section looks like this:

blacklist {
      wwid "26353900f02796769"
      devnode "^(ram|raw|loop|fd|md|dm-|sr|scd|st)[0-9]*"
      devnode "^sd[a-z][0-9]*"
}

You can also blacklist only the partitions from a driver instead of the entire array. For example, you can use the following regular expression to blacklist only partitions from the cciss driver and not the entire array:

blacklist {
      devnode "^cciss!c[0-9]d[0-9]*[p[0-9]*]"
}

You can blacklist by specific device types by adding a device section in the blacklist, and using the vendor and product keywords.

blacklist {
      device {
           vendor  "DELL"
           product ".*"
       }
}

You can use a blacklist_exceptions section to enable multipath for some devices that were blacklisted by the regular expressions used in the blacklist section. You add exceptions by WWID (wwid keyword), device name (devnode keyword), or device type (device section). You must specify the exceptions in the same way that you blacklisted the corresponding devices. That is, wwid exceptions apply to a wwid blacklist, devnode exceptions apply to a devnode blacklist, and device type exceptions apply to a device type blacklist.

For example, you can enable multipath for a desired device type when you have different device types from the same vendor. Blacklist all of the vendor’s device types in the blacklist section, and then enable multipath for the desired device type by adding a device section in a blacklist_exceptions section.

blacklist {
      devnode "^(ram|raw|loop|fd|md|dm-|sr|scd|st|sda)[0-9]*"
      device {
           vendor  "DELL"
           product ".*"
       }
}

blacklist_exceptions {
      device {
           vendor  "DELL"
           product "MD3220i"
       }
}

You can also use the blacklist_exceptions to enable multipath only for specific devices. For example:

blacklist {
      wwid ".*"
}

blacklist_exceptions {
        wwid "3600d0230000000000e13955cc3751234"
        wwid "3600d0230000000000e13955cc3751235"
}

After you have modified the /etc/multipath.conf file, you must run dracut -f to re-create the initrd on your system, then restart the server for the changes to take effect. See Section 17.6.4, “Applying the /etc/multipath.conf File Changes to Update the Multipath Maps” for details.

Following the reboot, the local devices should no longer be listed in the multipath maps when you issue the multipath -ll command.

Note
Note: Using the find_multipaths Option

Starting with SUSE Linux Enterprise Server 12 SP2, the multipath tools support the option find_multipaths in the defaults section of /etc/multipath.conf. Simply put, this option prevents multipath and multipathd from setting up multipath maps for devices with only a single path (see the man 5 multipath.conf for details). In certain configurations, this may save the administrator from the effort of creating blacklist entries, for example for local SATA disks.

Convenient as it seems at first, using the find_multipaths option also has disadvantages. It complicates and slows down the system boot, because for every device found, the boot logic needs to wait until all devices have been discovered to see whether a second path exists for the device. Additionally, problems can arise when some paths are down or otherwise invisible at boot time—a device can be falsely detected as a single-path device and activated, causing later addition of more paths to fail.

find_multipaths considers all devices that are listed in /etc/multipath/wwids with matching WWIDs as being multipath devices. This is important when find_multipaths is first activated: Unless /etc/multipath/wwids is deleted or edited, activating this option has no effect, because all previously existing multipath maps (including single-path ones) are listed in the wwids file. On SAN-boot systems with a multipathed root file system, make sure to keep /etc/multipath/wwids synchronized between the initial RAM disk and the file system.

In Summary, using find_multipaths may be convenient in certain use cases, but SUSE still recommends the default configuration with a properly configured blacklist and blacklist exceptions.

17.9 Configuring User-Friendly Names or Alias Names

A multipath device can be identified by its WWID, by a user-friendly name, or by an alias that you assign for it. Device node names in the form of /dev/sdn and /dev/dm-n can change on reboot and might be assigned to different devices each time. A device’s WWID, user-friendly name, and alias name persist across reboots, and are the preferred way to identify the device.

Important
Important: Using Persistent Names is Recommended

Because device node names in the form of /dev/sdn and /dev/dm-n can change on reboot, referring to multipath devices by their WWID is preferred. You can also use a user-friendly name or alias that is mapped to the WWID to identify the device uniquely across reboots.

The following table describes the types of device names that can be used for a device in the /etc/multipath.conf file. For an example of multipath.conf settings, see the /usr/share/doc/packages/multipath-tools/multipath.conf.synthetic file.

Table 17.4: Comparison of Multipath Device Name Types

Name Types

Description

WWID (default)

The serial WWID (Worldwide Identifier) is an identifier for the multipath device that is guaranteed to be globally unique and unchanging. The default name used in multipathing is the ID of the logical unit as found in the /dev/disk/by-id directory. For example, a device with the WWID of 3600508e0000000009e6baa6f609e7908 is listed as /dev/disk/by-id/scsi-3600508e0000000009e6baa6f609e7908.

User-friendly

The Device Mapper Multipath device names in the /dev/mapper directory also reference the ID of the logical unit. These multipath device names are user-friendly names in the form of /dev/mapper/mpathN, such as /dev/mapper/mpath0. The names are unique and persistent because they use the /var/lib/multipath/bindings file to track the association between the UUID and user-friendly names.

Alias

An alias name is a globally unique name that the administrator provides for a multipath device. Alias names override the WWID and the user-friendly /dev/mapper/mpathN names.

If you are using user_friendly_names, do not set the alias to mpathN format. This may conflict with an automatically assigned user-friendly name, and give you incorrect device node names.

The global multipath user_friendly_names option in the /etc/multipath.conf file is used to enable or disable the use of user-friendly names for multipath devices. If it is set to no (the default), multipath uses the WWID as the name of the device. If it is set to yes, multipath uses the /var/lib/multipath/bindings file to assign a persistent and unique name to the device in the form of mpath<N> in the /dev/mapper directory. The bindings file option in the /etc/multipath.conf file can be used to specify an alternate location for the bindings file.

The global multipath alias option in the /etc/multipath.conf file is used to explicitly assign a name to the device. If an alias name is set up for a multipath device, the alias is used instead of the WWID or the user-friendly name.

Using the user_friendly_names option can be problematic in the following situations:

Root Device Is Using Multipath:

If the system root device is using multipath and you use the user_friendly_names option, the user-friendly settings in the /var/lib/multipath/bindings file are included in the initrd. If you later change the storage setup, such as by adding or removing devices, there is a mismatch between the bindings setting inside the initrd and the bindings settings in /var/lib/multipath/bindings.

Warning
Warning: Binding Mismatches

A bindings mismatch between initrd and /var/lib/multipath/bindings can lead to a wrong assignment of mount points to devices, which can result in file system corruption and data loss.

To avoid this problem, we recommend that you use the default WWID settings for the system root device. You should not use aliases for the system root device. Because the device name would differ, using an alias causes you to lose the ability to seamlessly switch off multipathing via the kernel command line.

Mounting /var from Another Partition:

The default location of the user_friendly_names configuration file is /var/lib/multipath/bindings. If the /var data is not located on the system root device but mounted from another partition, the bindings file is not available when setting up multipathing.

Make sure that the /var/lib/multipath/bindings file is available on the system root device and multipath can find it. For example, this can be done as follows:

  1. Move the /var/lib/multipath/bindings file to /etc/multipath/bindings.

  2. Set the bindings_file option in the defaults section of /etc/multipath.conf to this new location. For example:

    defaults {
                   user_friendly_names yes
                   bindings_file "/etc/multipath/bindings"
    }
Multipath Is in the initrd:

Even if the system root device is not on multipath, it is possible for multipath to be included in the initrd. For example, this can happen if the system root device is on LVM. If you use the user_friendly_names option and multipath is in the initrd, you should boot with the parameter multipath=off to avoid problems.

This disables multipath only in the initrd during system boots. After the system boots, the boot.multipath and multipathd boot scripts can activate multipathing.

Multipathing in HA Clusters:

See Section 17.9.1, “Multipath Device Names in HA Clusters” for details.

To enable user-friendly names or to specify aliases:

  1. Open the /etc/multipath.conf file in a text editor with root privileges.

  2. (Optional) Modify the location of the /var/lib/multipath/bindings file.

    The alternate path must be available on the system root device where multipath can find it.

    1. Move the /var/lib/multipath/bindings file to /etc/multipath/bindings.

    2. Set the bindings_file option in the defaults section of /etc/multipath.conf to this new location. For example:

      defaults {
                user_friendly_names yes
                bindings_file "/etc/multipath/bindings"
      }
  3. (Optional, not recommended) Enable user-friendly names:

    1. Uncomment the defaults section and its ending bracket.

    2. Uncomment the user_friendly_names option, then change its value from No to Yes.

      For example:

      ## Use user-friendly names, instead of using WWIDs as names.
      defaults {
        user_friendly_names yes
      }
  4. (Optional) Specify your own names for devices by using the alias option in the multipath section.

    For example:

    ## Use alias names, instead of using WWIDs as names.
    multipaths {
           multipath {
                   wwid           36006048000028350131253594d303030
                   alias             blue1
           }
           multipath {
                   wwid           36006048000028350131253594d303041
                   alias             blue2
           }
           multipath {
                   wwid           36006048000028350131253594d303145
                   alias             yellow1
           }
           multipath {
                   wwid           36006048000028350131253594d303334
                   alias             yellow2
           }
    }
    Important
    Important: WWWID Compared to WWN

    When you define device aliases in the /etc/multipath.conf file, ensure that you use each device’s WWID (such as 3600508e0000000009e6baa6f609e7908) and not its WWN, which replaces the first character of a device ID with 0x, such as 0x600508e0000000009e6baa6f609e7908.

  5. Save your changes, then close the file.

  6. After you have modified the /etc/multipath.conf file, you must run dracut -f to re-create the initrd on your system, then restart the server for the changes to take effect. See Section 17.6.4, “Applying the /etc/multipath.conf File Changes to Update the Multipath Maps” for details.

To use the entire LUN directly (for example, if you are using the SAN features to partition your storage), you can use the /dev/disk/by-id/xxx names for mkfs, fstab, your application, and so on. Partitioned devices have _part<n> appended to the device name, such as /dev/disk/by-id/xxx_part1.

In the /dev/disk/by-id directory, the multipath-mapped devices are represented by the device’s dm-uuid* name or alias name (if you assign an alias for it in the /etc/multipath.conf file). The scsi- and wwn- device names represent physical paths to the devices.

17.9.1 Multipath Device Names in HA Clusters

Make sure that multipath devices have the same name across all devices by doing the following:

  • Use UUID and alias names to ensure that multipath device names are consistent across all nodes in the cluster. Alias names must be unique across all nodes. Copy the /etc/multipath.conf file from the node to the /etc/ directory for all of the other nodes in the cluster.

  • When using links to multipath-mapped devices, ensure that you specify the dm-uuid* name or alias name in the /dev/disk/by-id directory, and not a fixed path instance of the device. For information, see Section 17.9, “Configuring User-Friendly Names or Alias Names”.

  • Set the user_friendly_names configuration option to no to disable it. A user-friendly name is unique to a node, but a device might not be assigned the same user-friendly name on every node in the cluster.

Note
Note: User-Friendly Names

If you really need to use user-friendly names, you can force the system-defined user-friendly names to be consistent across all nodes in the cluster by doing the following:

  1. In the /etc/multipath.conf file on one node:

    1. Set the user_friendly_names configuration option to yes to enable it.

      Multipath uses the /var/lib/multipath/bindings file to assign a persistent and unique name to the device in the form of mpath<N> in the /dev/mapper directory.

    2. (Optional) Set the bindings_file option in the defaults section of the /etc/multipath.conf file to specify an alternate location for the bindings file.

      The default location is /var/lib/multipath/bindings.

  2. Set up all of the multipath devices on the node.

  3. Copy the /etc/multipath.conf file from the node to the /etc/ directory of all the other nodes in the cluster.

  4. Copy the bindings file from the node to the bindings_file path on all of the other nodes in the cluster.

  5. After you have modified the /etc/multipath.conf file, you must run dracut -f to re-create the initrd on your system, then restart the node for the changes to take effect. See Section 17.6.4, “Applying the /etc/multipath.conf File Changes to Update the Multipath Maps” for details. This applies to all affected nodes.

17.10 Configuring Path Failover Policies and Priorities

In a Linux host, when there are multiple paths to a storage controller, each path appears as a separate block device, and results in multiple block devices for single LUN. The Device Mapper Multipath service detects multiple paths with the same LUN ID, and creates a new multipath device with that ID. For example, a host with two HBAs attached to a storage controller with two ports via a single unzoned Fibre Channel switch sees four block devices: /dev/sda, /dev/sdb, /dev/sdc, and /dev/sdd. The Device Mapper Multipath service creates a single block device, /dev/mpath/mpath1, that reroutes I/O through those four underlying block devices.

This section describes how to specify policies for failover and configure priorities for the paths. Note that after you have modified the /etc/multipath.conf file, you must run dracut -f to re-create the initrd on your system, then restart the server for the changes to take effect. See Section 17.6.4, “Applying the /etc/multipath.conf File Changes to Update the Multipath Maps” for details.

17.10.1 Configuring the Path Failover Policies

Use the multipath command with the -p option to set the path failover policy:

sudo multipath DEVICENAME -p POLICY

Replace POLICY with one of the following policy options:

Table 17.5: Group Policy Options for the multipath -p Command

Policy Option

Description

failover

(Default) One path per priority group.

multibus

All paths in one priority group.

group_by_serial

One priority group per detected serial number.

group_by_prio

One priority group per path priority value. Priorities are determined by callout programs specified as a global, per-controller, or per-multipath option in the /etc/multipath.conf configuration file.

group_by_node_name

One priority group per target node name. Target node names are fetched in the /sys/class/fc_transport/target*/node_name location.

17.10.2 Configuring Failover Priorities

You must manually enter the failover priorities for the device in the /etc/multipath.conf file. Examples for all settings and options can be found in the /usr/share/doc/packages/multipath-tools/multipath.conf.annotated file.

17.10.2.1 Understanding Priority Groups and Attributes

A priority group is a collection of paths that go to the same physical LUN. By default, I/O is distributed in a round-robin fashion across all paths in the group. The multipath command automatically creates priority groups for each LUN in the SAN based on the path_grouping_policy setting for that SAN. The multipath command multiplies the number of paths in a group by the group’s priority to determine which group is the primary. The group with the highest calculated value is the primary. When all paths in the primary group are failed, the priority group with the next highest value becomes active.

A path priority is an integer value assigned to a path. The higher the value, the higher the priority. An external program is used to assign priorities for each path. For a given device, the paths with the same priorities belong to the same priority group.

The prio setting is used in the defaults{} or devices{} section of the /etc/multipath.conf file. It is silently ignored when it is specified for an individual multipath definition in the multipaths{) section. The prio line specifies the prioritizer. If the prioritizer requires an argument, you specify the argument by using the prio_args keyword on a second line.

PRIO Settings for the Defaults or Devices Sections

prio

Specifies the prioritizer program to call to obtain a path priority value. Weights are summed for each path group to determine the next path group to use in case of failure.

Use the prio_args keyword to specify arguments if the specified prioritizer requires arguments.

If no prio keyword is specified, all paths are equal. The default setting is const with a prio_args setting with no value.

prio "const"
prio_args ""

Example prioritizer programs include:

Prioritizer Program

Description

alua

Generates path priorities based on the SCSI-3 ALUA settings.

const

Generates the same priority for all paths.

emc

Generates the path priority for EMC arrays.

hdc

Generates the path priority for Hitachi HDS Modular storage arrays.

hp_sw

Generates the path priority for Compaq/HP controller in active/standby mode.

ontap

Generates the path priority for NetApp arrays.

random

Generates a random priority for each path.

rdac

Generates the path priority for LSI/Engenio RDAC controller.

weightedpath

Generates the path priority based on the weighted values you specify in the arguments for prio_args, such as:

[hbtl|devname] REGEX1 PRIO1 REGEX2 PRIO2...

The hbtl regex argument format uses the SCSI H:B:T:L notation (such as 1:0:.:. and *:0:0:.) with a weight value, where H, B, T, L are the host, bus, target, and LUN IDs for a device. For example:

prio "weightedpath"
prio_args "hbtl 1:.:.:. 2 4:.:.:. 4"

The devname regular expression argument format uses a device node name with a weight value for each device. For example:

prio "weightedpath"
prio_args "devname sda 50 sde 10 sdc 50 sdf 10"
prio_args

Specifies the arguments for the specified prioritizer program that requires arguments. Most prio programs do not need arguments.

There is no default. The value depends on the prio setting and whether the prioritizer requires arguments.

Multipath Attributes

Multipath attributes are used to control the behavior of multipath I/O for devices. You can specify attributes as defaults for all multipath devices. You can also specify attributes that apply only to a given multipath device by creating an entry for that device in the multipaths section of the multipath configuration file.

user_friendly_names

Specifies whether to use world-wide IDs (WWIDs) or to use the /var/lib/multipath/bindings file to assign a persistent and unique alias to the multipath devices in the form of /dev/mapper/mpathN.

This option can be used in the devices section and the multipaths section.

Value

Description

no

(Default) Use the WWIDs shown in the /dev/disk/by-id/ location.

yes

Autogenerate user-friendly names as aliases for the multipath devices instead of the actual ID.

failback

Specifies whether to monitor the failed path recovery, and indicates the timing for group failback after failed paths return to service.

When the failed path recovers, the path is added back into the multipath-enabled path list based on this setting. Multipath evaluates the priority groups, and changes the active priority group when the priority of the primary path exceeds the secondary group.

Value

Description

manual

(Default) The failed path is not monitored for recovery. The administrator runs the multipath command to update enabled paths and priority groups.

followover

Only perform automatic failback when the first path of a pathgroup becomes active. This keeps a node from automatically failing back when another node requested the failover.

immediate

When a path recovers, enable the path immediately.

N

When the path recovers, wait N seconds before enabling the path. Specify an integer value greater than 0.

We recommend failback setting of manual for multipath in cluster environments to prevent multipath failover ping-pong.

failback "manual"
Important
Important: Verification

Make sure that you verify the failback setting with your storage system vendor. Different storage systems can require different settings.

no_path_retry

Specifies the behaviors to use on path failure.

Value

Description

N

Specifies the number of retries until multipath stops the queuing and fails the path. Specify an integer value greater than 0.

In a cluster, you can specify a value of “0” to prevent queuing and allow resources to fail over.

fail

Specifies immediate failure (no queuing).

queue

Never stop queuing (queue forever until the path comes alive).

We recommend a retry setting of fail or 0 in the /etc/multipath.conf file when working in a cluster. This causes the resources to fail over when the connection is lost to storage. Otherwise, the messages queue and the resource failover cannot occur.

no_path_retry "fail"
no_path_retry "0"
Important
Important: Verification

Make sure that you verify the retry settings with your storage system vendor. Different storage systems can require different settings.

path_checker

Determines the state of the path.

Value

Description

directio

Reads the first sector that has direct I/O. This is useful for DASD devices. Logs failure messages in the systemd journal (see Chapter 15, journalctl: Query the systemd Journal).

tur

Issues an SCSI test unit ready command to the device. This is the preferred setting if the LUN supports it. On failure, the command does not fill up the systemd log journal with messages.

CUSTOM_VENDOR_VALUE

Some SAN vendors provide custom path_checker options:

  • cciss_tur Checks the path state for HP Smart Storage Arrays.

  • emc_clariion Queries the EMC Clariion EVPD page 0xC0 to determine the path state.

  • hp_sw Checks the path state (Up, Down, or Ghost) for HP storage arrays with Active/Standby firmware.

  • rdac Checks the path state for the LSI/Engenio RDAC storage controller.

path_grouping_policy

Specifies the path grouping policy for a multipath device hosted by a given controller.

Value

Description

failover

(Default) One path is assigned per priority group so that only one path at a time is used.

multibus

All valid paths are in one priority group. Traffic is load-balanced across all active paths in the group.

group_by_prio

One priority group exists for each path priority value. Paths with the same priority are in the same priority group. Priorities are assigned by an external program.

group_by_serial

Paths are grouped by the SCSI target serial number (controller node WWN).

group_by_node_name

One priority group is assigned per target node name. Target node names are fetched in /sys/class/fc_transport/target*/node_name.

path_selector

Specifies the path-selector algorithm to use for load balancing.

Value

Description

round-robin 0

The load-balancing algorithm used to balance traffic across all active paths in a priority group.

queue-length 0

A dynamic load balancer that balances the number of in-flight I/O on paths similar to the least-pending option.

service-time 0

(Default) A service-time oriented load balancer that balances I/O on paths according to the latency.

pg_timeout

Specifies path group timeout handling. No value can be specified; an internal default is set.

polling_interval

Specifies the time in seconds between the end of one path checking cycle and the beginning of the next path checking cycle.

Specify an integer value greater than 0. The default value is 5. Make sure that you verify the polling_interval setting with your storage system vendor. Different storage systems can require different settings.

rr_min_io_rq

Specifies the number of I/O requests to route to a path before switching to the next path in the current path group, using request-based device-mapper-multipath.

Specify an integer value greater than 0. The default value is 1.

rr_min_io_rq "1"
rr_weight

Specifies the weighting method to use for paths.

Value

Description

uniform

(Default) All paths have the same round-robin weights.

priorities

Each path’s weight is determined by the path’s priority times the rr_min_io_rq setting.

uid_attribute

A udev attribute that provides a unique path identifier. The default value is ID_SERIAL.

17.10.2.2 Configuring for Round-Robin Load Balancing

All paths are active. I/O is configured for some number of seconds or some number of I/O transactions before moving to the next open path in the sequence.

17.10.2.3 Configuring for Single Path Failover

A single path with the highest priority (lowest value setting) is active for traffic. Other paths are available for failover, but are not used unless failover occurs.

17.10.2.4 Grouping I/O Paths for Round-Robin Load Balancing

Multiple paths with the same priority fall into the active group. When all paths in that group fail, the device fails over to the next highest priority group. All paths in the group share the traffic load in a round-robin load balancing fashion.

17.10.3 Reporting Target Path Groups

Use the SCSI Report Target Port Groups (sg_rtpg(8)) command. For information, see the man page for sg_rtpg(8).

17.11 Configuring Multipath I/O for the Root Device

Device Mapper Multipath I/O (DM-MPIO) is available and supported for /boot and /root in SUSE Linux Enterprise Server. In addition, the YaST partitioner in the YaST installer supports enabling multipath during the install.

17.11.1 Enabling Multipath I/O at Install Time

To install the operating system on a multipath device, the multipath software must be running at install time. The multipathd daemon is not automatically active during the system installation. You can start it by using the Configure Multipath option in the YaST Partitioner.

17.11.1.1 Enabling Multipath I/O at Install Time on an Active/Active Multipath Storage LUN

  1. Choose Expert Partitioner on the Suggested Partitioning screen during the installation.

  2. Select the Hard Disks main icon, click the Configure button, then select Configure Multipath.

  3. Start multipath.

    YaST starts to rescan the disks and shows available multipath devices (such as /dev/disk/by-id/dm-uuid-mpath-3600a0b80000f4593000012ae4ab0ae65). This is the device that should be used for all further processing.

  4. Click Next to continue with the installation.

17.11.1.2 Enabling Multipath I/O at Install Time on an Active/Passive Multipath Storage LUN

The multipathd daemon is not automatically active during the system installation. You can start it by using the Configure Multipath option in the YaST Partitioner.

To enable multipath I/O at install time for an active/passive multipath storage LUN:

  1. Choose Expert Partitioner on the Suggested Partitioning screen during the installation.

  2. Select the Hard Disks main icon, click the Configure button, then select Configure Multipath.

  3. Start multipath.

    YaST starts to rescan the disks and shows available multipath devices (such as /dev/disk/by-id/dm-uuid-mpath-3600a0b80000f4593000012ae4ab0ae65). This is the device that should be used for all further processing. Write down the device path and UUID; you will need it later.

  4. Click Next to continue with the installation.

  5. After all settings are done and the installation is finished, YaST starts to write the boot loader information, and displays a countdown to restart the system. Stop the counter by clicking the Stop button and press CtrlAltF5 to access a console.

  6. Use the console to determine if a passive path was entered in the /boot/grub2/device.map file for the hd0 entry.

    This is necessary because the installation does not distinguish between active and passive paths.

    1. Mount the root device to /mnt by entering

      mount /dev/disk/by-id/UUID;_part2 /mnt

      For example, enter

      mount /dev/disk/by-id/dm-uuid-mpath-3600a0b80000f4593000012ae4ab0ae65_part2 /mnt
    2. Mount the boot device to /mnt/boot by entering

      mount /dev/disk/by-id/UUID_part1 /mnt/boot

      For example, enter

      mount /dev/disk/by-id/dm-uuid-mpath-3600a0b80000f4593000012ae4ab0ae65_part2 /mnt/boot
    3. In the /mnt/boot/grub2/device.map file, determine if the hd0 entry points to a passive path, then do one of the following:

      • Active path:  No action is needed. Skip all remaining steps and return to the YaST graphical environment by pressing CtrlAltF7 and continue with the installation.

      • Passive path:  The configuration must be changed and the boot loader must be reinstalled.

  7. If the hd0 entry points to a passive path, change the configuration and reinstall the boot loader:

    1. Enter the following commands at the console prompt:

                mount -o bind /dev /mnt/dev
                mount -o bind /sys /mnt/sys
                mount -o bind /proc /mnt/proc
                chroot /mnt
    2. At the console, run multipath -ll, then check the output to find the active path.

      Passive paths are flagged as ghost.

    3. In the /boot/grub2/device.map file, change the hd0 entry to an active path, save the changes, and close the file.

    4. Reinstall the boot loader by entering

                grub-install /dev/disk/by-id/UUID_part1 /mnt/boot

      For example, enter

      grub-install /dev/disk/by-id/dm-uuid-mpath-3600a0b80000f4593000012ae4ab0ae65_part2 /mnt/boot
    5. Enter the following commands:

      exit
      umount /mnt/*
      umount /mnt
  8. Return to the YaST graphical environment by pressing CtrlAltF7.

  9. Click OK to continue with the installation reboot.

17.11.2 Enabling Multipath I/O for an Existing Root Device

  1. Install Linux with only a single path active, preferably one where the by-id symbolic links are listed in the partitioner.

  2. Mount the devices by using the /dev/disk/by-id path used during the install.

  3. Add dm-multipath to /etc/dracut.conf.d/01-dist.conf by adding the following line:

    force_drivers+="dm-multipath"
  4. For IBM z Systems, before running dracut, edit the /etc/zipl.conf file to change the by-path information in zipl.conf with the same by-id information that was used in /etc/fstab.

  5. Run dracut -f to update the initrd image.

  6. For IBM z Systems, after running dracut, run zipl.

  7. Reboot the server.

17.11.3 Disabling Multipath I/O on the Root Device

Add multipath=off to the kernel command line. This can be done with the YaST Boot Loader module. Open Boot Loader Installation › Kernel Parameters and add the parameter to both command lines.

This affects only the root device. All other devices are not affected.

17.12 Configuring Multipath I/O for an Existing Software RAID

Ideally, you should configure multipathing for devices before you use them as components of a software RAID device. If you add multipathing after creating any software RAID devices, the DM-MPIO service might be starting after the multipath service on reboot, which makes multipathing appear not to be available for RAIDs. You can use the procedure in this section to get multipathing running for a previously existing software RAID.

For example, you might need to configure multipathing for devices in a software RAID under the following circumstances:

  • If you create a new software RAID as part of the Partitioning settings during a new install or upgrade.

  • If you did not configure the devices for multipathing before using them in the software RAID as a member device or spare.

  • If you grow your system by adding new HBA adapters to the server or expanding the storage subsystem in your SAN.

Note
Note: Assumptions

The following instructions assume the software RAID device is /dev/mapper/mpath0, which is its device name as recognized by the kernel. It assumes you have enabled user-friendly names in the /etc/multipath.conf file as described in Section 17.9, “Configuring User-Friendly Names or Alias Names”.

Make sure to modify the instructions for the device name of your software RAID.

  1. Open a terminal console.

    Except where otherwise directed, use this console to enter the commands in the following steps.

  2. If any software RAID devices are currently mounted or running, enter the following commands for each device to unmount the device and stop it.

    sudo umount /dev/mapper/mpath0
    sudo mdadm --misc --stop /dev/mapper/mpath0
  3. Stop the md service by entering

    sudo systemctl stop mdmonitor
  4. Start the multipathd daemon by entering the following command:

    systemctl start multipathd
  5. After the multipathing service has been started, verify that the software RAID’s component devices are listed in the /dev/disk/by-id directory. Do one of the following:

    • Devices Are Listed:  The device names should now have symbolic links to their Device Mapper Multipath device names, such as /dev/dm-1.

    • Devices Are Not Listed:  Force the multipath service to recognize them by flushing and rediscovering the devices by entering

      sudo multipath -F
      sudo multipath -v0

      The devices should now be listed in /dev/disk/by-id, and have symbolic links to their Device Mapper Multipath device names. For example:

      lrwxrwxrwx 1 root root 10 2011-01-06 11:42 dm-uuid-mpath-36006016088d014007e0d0d2213ecdf11 -> ../../dm-1
  6. Restart the mdmonitor service and the RAID device by entering

    systemctl start mdmonitor
  7. Check the status of the software RAID by entering

    mdadm --detail /dev/mapper/mpath0

    The RAID’s component devices should match their Device Mapper Multipath device names that are listed as the symbolic links of devices in the /dev/disk/by-id directory.

  8. In case the root (/) device or any parts of it (such as /var, /etc, /log) are on the SAN and multipath is needed to boot, rebuild the initrd:

    dracut -f --add-multipath
  9. Reboot the server to apply the changes.

  10. Verify that the software RAID array comes up properly on top of the multipathed devices by checking the RAID status. Enter

    mdadm --detail /dev/mapper/mpath0

    For example:

    Number Major Minor RaidDevice State
    0 253 0 0 active sync /dev/dm-0
    1 253 1 1 active sync /dev/dm-1
    2 253 2 2 active sync /dev/dm-2
Note
Note: Using mdadm with Multipath Devices

The mdadm tool requires that the devices be accessed by the ID rather than by the device node path. Refer to Section 17.4.3, “Using MDADM for Multipathed Devices” for details.

17.13 Using LVM2 on Multipath Devices

When using multipath, all paths to a resource are present as devices in the device tree. By default LVM checks if there is a multipath device on top of any device in the device tree. If LVM finds a multipath device on top, it assumes that the device is a multipath component and ignores the (underlying) device. This is the most likely desired behavior, but it can be changed in /etc/lvm/lvm.conf. When multipath_component_detection is set to 0, LVM is scanning multipath component devices. The default entry in lvm.conf is:

    # By default, LVM2 will ignore devices used as component paths
    # of device-mapper multipath devices.
    # 1 enables; 0 disables.
    multipath_component_detection = 1

17.14 Best Practice

17.14.1 Scanning for New Devices without Rebooting

If your system has already been configured for multipathing and you later need to add more storage to the SAN, you can use the rescan-scsi-bus.sh script to scan for the new devices. By default, this script scans all HBAs with typical LUN ranges. The general syntax for the command looks like the following:

rescan-scsi-bus.sh [options] [host [host ...]]

For most storage subsystems, the script can be run successfully without options. However, some special cases might need to use one or more options. Run rescan-scsi-bus.sh --help for details.

Warning
Warning: EMC PowerPath Environments

In EMC PowerPath environments, do not use the rescan-scsi-bus.sh utility provided with the operating system or the HBA vendor scripts for scanning the SCSI buses. To avoid potential file system corruption, EMC requires that you follow the procedure provided in the vendor documentation for EMC PowerPath for Linux.

Use the following procedure to scan the devices and make them available to multipathing without rebooting the system.

  1. On the storage subsystem, use the vendor’s tools to allocate the device and update its access control settings to allow the Linux system access to the new storage. Refer to the vendor’s documentation for details.

  2. Scan all targets for a host to make its new device known to the middle layer of the Linux kernel’s SCSI subsystem. At a terminal console prompt, enter

    sudo rescan-scsi-bus.sh

    Depending on your setup, you might need to run rescan-scsi-bus.sh with optional parameters. Refer to rescan-scsi-bus.sh --help for details.

  3. Check for scanning progress in the systemd journal (see Chapter 15, journalctl: Query the systemd Journal for details). At a terminal console prompt, enter

    sudo journalctl -r

    This command displays the last lines of the log. For example:

    tux > sudo journalctl -r
    Feb 14 01:03 kernel: SCSI device sde: 81920000
    Feb 14 01:03 kernel: SCSI device sdf: 81920000
    Feb 14 01:03 multipathd: sde: path checker registered
    Feb 14 01:03 multipathd: sdf: path checker registered
    Feb 14 01:03 multipathd: mpath4: event checker started
    Feb 14 01:03 multipathd: mpath5: event checker started
    Feb 14 01:03:multipathd: mpath4: remaining active paths: 1
    Feb 14 01:03 multipathd: mpath5: remaining active paths: 1
    [...]
  4. Repeat the previous steps to add paths through other HBA adapters on the Linux system that are connected to the new device.

  5. Run the multipath command to recognize the devices for DM-MPIO configuration. At a terminal console prompt, enter

    sudo multipath

    You can now configure the new device for multipathing.

17.14.2 Scanning for New Partitioned Devices without Rebooting

Use the example in this section to detect a newly added multipathed LUN without rebooting.

Warning
Warning: EMC PowerPath Environments

In EMC PowerPath environments, do not use the rescan-scsi-bus.sh utility provided with the operating system or the HBA vendor scripts for scanning the SCSI buses. To avoid potential file system corruption, EMC requires that you follow the procedure provided in the vendor documentation for EMC PowerPath for Linux.

  1. Open a terminal console.

  2. Scan all targets for a host to make its new device known to the middle layer of the Linux kernel’s SCSI subsystem. At a terminal console prompt, enter

    rescan-scsi-bus.sh

    Depending on your setup, you might need to run rescan-scsi-bus.sh with optional parameters. Refer to rescan-scsi-bus.sh --help for details.

  3. Verify that the device is seen (such as if the link has a new time stamp) by entering

    ls -lrt /dev/dm-*

    You can also verify the devices in /dev/disk/by-id by entering

    ls -l /dev/disk/by-id/
  4. Verify the new device appears in the log by entering

    sudo journalctl -r
  5. Use a text editor to add a new alias definition for the device in the /etc/multipath.conf file, such as data_vol3.

    For example, if the UUID is 36006016088d014006e98a7a94a85db11, make the following changes:

    defaults {
         user_friendly_names   yes
      }
    multipaths {
         multipath {
              wwid    36006016088d014006e98a7a94a85db11
              alias  data_vol3
              }
      }
  6. Create a partition table for the device by entering

    fdisk /dev/disk/by-id/dm-uuid-mpath-<UUID>

    Replace UUID with the device WWID, such as 36006016088d014006e98a7a94a85db11.

  7. Trigger udev by entering

    sudo echo 'add' > /sys/block/DM_DEVICE/uevent

    For example, to generate the device-mapper devices for the partitions on dm-8, enter

    sudo echo 'add' > /sys/block/dm-8/uevent
  8. Create a file system on the device /dev/disk/by-id/dm-uuid-mpath-UUID_partN. Depending on your choice for the file system, you may use one of the following commands for this purpose: mkfs.btrfs mkfs.ext3, mkfs.ext4, or mkfs.xfs. Refer to the respective man pages for details. Replace UUID_partN with the actual UUID and partition number, such as 36006016088d014006e98a7a94a85db11_part1.

  9. Create a label for the new partition by entering the following command:

    sudo tune2fs -L LABELNAME /dev/disk/by-id/dm-uuid-UUID_partN

    Replace UUID_partN with the actual UUID and partition number, such as 36006016088d014006e98a7a94a85db11_part1. Replace LABELNAME with a label of your choice.

  10. Reconfigure DM-MPIO to let it read the aliases by entering

    sudo multipathd -k'reconfigure'
  11. Verify that the device is recognized by multipathd by entering

    sudo multipath -ll
  12. Use a text editor to add a mount entry in the /etc/fstab file.

    At this point, the alias you created in a previous step is not yet in the /dev/disk/by-label directory. Add a mount entry for the /dev/dm-9 path, then change the entry before the next time you reboot to

    LABEL=LABELNAME
  13. Create a directory to use as the mount point, then mount the device.

17.14.3 Viewing Multipath I/O Status

Querying the multipath I/O status outputs the current status of the multipath maps.

The multipath -l option displays the current path status as of the last time that the path checker was run. It does not run the path checker.

The multipath -ll option runs the path checker, updates the path information, then displays the current status information. This command always displays the latest information about the path status.

tux > sudo multipath -ll
3600601607cf30e00184589a37a31d911
[size=127 GB][features="0"][hwhandler="1 emc"]

\_ round-robin 0 [active][first]
  \_ 1:0:1:2 sdav 66:240  [ready ][active]
  \_ 0:0:1:2 sdr  65:16   [ready ][active]

\_ round-robin 0 [enabled]
  \_ 1:0:0:2 sdag 66:0    [ready ][active]
  \_ 0:0:0:2 sdc  8:32    [ready ][active]

For each device, it shows the device’s ID, size, features, and hardware handlers.

Paths to the device are automatically grouped into priority groups on device discovery. Only one priority group is active at a time. For an active/active configuration, all paths are in the same group. For an active/passive configuration, the passive paths are placed in separate priority groups.

The following information is displayed for each group:

  • Scheduling policy used to balance I/O within the group, such as round-robin

  • Whether the group is active, disabled, or enabled

  • Whether the group is the first (highest priority) group

  • Paths contained within the group

The following information is displayed for each path:

  • The physical address as HOST:BUS:TARGET:LUN, such as 1:0:1:2

  • Device node name, such as sda

  • Major:minor numbers

  • Status of the device

17.14.4 Managing I/O in Error Situations

You might need to configure multipathing to queue I/O if all paths fail concurrently by enabling queue_if_no_path. Otherwise, I/O fails immediately if all paths are gone. In certain scenarios, where the driver, the HBA, or the fabric experience spurious errors, DM-MPIO should be configured to queue all I/O where those errors lead to a loss of all paths, and never propagate errors upward.

When you use multipathed devices in a cluster, you might choose to disable queue_if_no_path. This automatically fails the path instead of queuing the I/O, and escalates the I/O error to cause a failover of the cluster resources.

Because enabling queue_if_no_path leads to I/O being queued indefinitely unless a path is reinstated, ensure that multipathd is running and works for your scenario. Otherwise, I/O might be stalled indefinitely on the affected multipathed device until reboot or until you manually return to failover instead of queuing.

To test the scenario:

  1. Open a terminal console.

  2. Activate queuing instead of failover for the device I/O by entering

    sudo dmsetup message DEVICE_ID 0 queue_if_no_path

    Replace the DEVICE_ID with the ID for your device. The 0 value represents the sector and is used when sector information is not needed.

    For example, enter:

    sudo dmsetup message 3600601607cf30e00184589a37a31d911 0 queue_if_no_path
  3. Return to failover for the device I/O by entering

    sudo dmsetup message DEVICE_ID 0 fail_if_no_path

    This command immediately causes all queued I/O to fail.

    Replace the DEVICE_ID with the ID for your device. For example, enter

    sudo dmsetup message 3600601607cf30e00184589a37a31d911 0 fail_if_no_path

To set up queuing I/O for scenarios where all paths fail:

  1. Open a terminal console.

  2. Open the /etc/multipath.conf file in a text editor.

  3. Uncomment the defaults section and its ending bracket, then add the default_features setting, as follows:

    defaults {
      default_features "1 queue_if_no_path"
    }
  4. After you modify the /etc/multipath.conf file, you must run dracut -f to re-create the initrd on your system, then reboot for the changes to take effect.

  5. When you are ready to return to failover for the device I/O, enter

    sudo dmsetup message MAPNAME 0 fail_if_no_path

    Replace the MAPNAME with the mapped alias name or the device ID for the device. The 0 value represents the sector and is used when sector information is not needed.

    This command immediately causes all queued I/O to fail and propagates the error to the calling application.

17.14.5 Resolving Stalled I/O

If all paths fail concurrently and I/O is queued and stalled, do the following:

  1. Enter the following command at a terminal console prompt:

    sudo dmsetup message MAPNAME 0 fail_if_no_path

    Replace MAPNAME with the correct device ID or mapped alias name for the device. The 0 value represents the sector and is used when sector information is not needed.

    This command immediately causes all queued I/O to fail and propagates the error to the calling application.

  2. Reactivate queuing by entering the following command:

    sudo dmsetup message MAPNAME 0 queue_if_no_path

17.14.6 Configuring Default Settings for IBM z Systems Devices

Testing of the IBM z Systems device with multipathing has shown that the dev_loss_tmo parameter should be set to 90 seconds, and the fast_io_fail_tmo parameter should be set to 5 seconds. If you are using z Systems devices, modify the /etc/multipath.conf file to specify the values as follows:

defaults {
       dev_loss_tmo 90
       fast_io_fail_tmo 5
}

The dev_loss_tmo parameter sets the number of seconds to wait before marking a multipath link as bad. When the path fails, any current I/O on that failed path fails. The default value varies according to the device driver being used. The valid range of values is 0 to 600 seconds. To use the driver’s internal timeouts, set the value to zero (0) or to any value greater than 600.

The fast_io_fail_tmo parameter sets the length of time to wait before failing I/O when a link problem is detected. I/O that reaches the driver fails. If I/O is in a blocked queue, the I/O does not fail until the dev_loss_tmo time elapses and the queue is unblocked.

If you modify the /etc/multipath.conf file, the changes are not applied until you update the multipath maps, or until the multipathd daemon is restarted (systemctl restart multipathd).

17.14.7 Using Multipath with NetApp Devices

When using multipath for NetApp devices, we recommend the following settings in the /etc/multipath.conf file:

  • Set the default values for the following parameters globally for NetApp devices:

    max_fds max
    queue_without_daemon no
  • Set the default values for the following parameters for NetApp devices in the hardware table:

    dev_loss_tmo infinity
    fast_io_fail_tmo 5
    features "3 queue_if_no_path pg_init_retries 50"

17.14.8 Using --noflush with Multipath Devices

The --noflush option should always be used when running on multipath devices.

For example, in scripts where you perform a table reload, you use the --noflush option on resume to ensure that any outstanding I/O is not flushed, because you need the multipath topology information.

load
resume --noflush

17.14.9 SAN Timeout Settings When the Root Device Is Multipathed

A system with root (/) on a multipath device might stall when all paths have failed and are removed from the system because a dev_loss_tmo timeout is received from the storage subsystem (such as Fibre Channel storage arrays).

If the system device is configured with multiple paths and the multipath no_path_retry setting is active, you should modify the storage subsystem’s dev_loss_tmo setting accordingly to ensure that no devices are removed during an all-paths-down scenario. We strongly recommend that you set the dev_loss_tmo value to be equal to or higher than the no_path_retry setting from multipath.

The recommended setting for the storage subsystem’s dev_los_tmo is

<dev_loss_tmo> = <no_path_retry> * <polling_interval>

where the following definitions apply for the multipath values:

  • no_path_retry is the number of retries for multipath I/O until the path is considered to be lost, and queuing of IO is stopped.

  • polling_interval is the time in seconds between path checks.

Each of these multipath values should be set from the /etc/multipath.conf configuration file. For information, see Section 17.6, “Creating or Modifying the /etc/multipath.conf File”.

17.15 Troubleshooting MPIO

This section describes some known issues and possible solutions for MPIO.

17.15.1 The System Exits to Emergency Shell at Boot When Multipath Is Enabled

During boot the system exits into the emergency shell with messages similar to the following:

[  OK  ] Listening on multipathd control socket.
         Starting Device-Mapper Multipath Device Controller...
[  OK  ] Listening on Device-mapper event daemon FIFOs.
         Starting Device-mapper event daemon...
         Expecting device dev-disk-by\x2duuid-34be48b2\x2dc21...32dd9.device...
         Expecting device dev-sda2.device...
[  OK  ] Listening on udev Kernel Socket.
[  OK  ] Listening on udev Control Socket.
         Starting udev Coldplug all Devices...
         Expecting device dev-disk-by\x2duuid-1172afe0\x2d63c...5d0a7.device...
         Expecting device dev-disk-by\x2duuid-c4a3d1de\x2d4dc...ef77d.device...
[  OK  ] Started Create list of required static device nodes ...current kernel.
         Starting Create static device nodes in /dev...
[  OK  ] Started Collect Read-Ahead Data.
[  OK  ] Started Device-mapper event daemon.
[  OK  ] Started udev Coldplug all Devices.
         Starting udev Wait for Complete Device Initialization...
[  OK  ] Started Replay Read-Ahead Data.
         Starting Load Kernel Modules...
         Starting Remount Root and Kernel File Systems...
[  OK  ] Started Create static devices
[   13.682489] floppy0: no floppy controllers found
[*     ] (1 of 4) A start job is running for dev-disk-by\x2du...(7s / 1min 30s)
[*     ] (1 of 4) A start job is running for dev-disk-by\x2du...(7s / 1min 30s)

...

Timed out waiting for device dev-disk-by\x2duuid-c4a...cfef77d.device.
[DEPEND] Dependency failed for /opt.
[DEPEND] Dependency failed for Local File Systems.
[DEPEND] Dependency failed for Postfix Mail Transport Agent.
Welcome to emergency shell
Give root password for maintenance
(or press Control-D to continue):

This issue occurs in the following situations:

Procedure 17.1: Emergency Shell: Blacklist File Systems

This fix is required if the root file system is not on multipath but multipath is enabled. In such a setup, multipath tries to set its paths for all devices that are not blacklisted. Since the device with the root file system is already mounted, it is inaccessible for multipath and causes it to fail. Fix this issue by configuring multipath correctly by blacklisting the root device in /etc/multipath.conf:

  1. Run multipath -v2 in the emergency shell and identify the device for the root file system. It will result in an output similar to:

    root # multipath -v2
    Dec 18 10:10:03 | 3600508b1001030343841423043300400: ignoring map

    The string between | and : is the WWID needed for blacklisting.

  2. Open /etc/multipath.conf and add the following:

    blacklist {
      wwid "WWWID"
    }

    Replace WWWID with the ID you retrieved in the previous step. For more information see Section 17.8, “Blacklisting Non-Multipath Devices”.

  3. Exit the emergency shell and reboot the server by pressing CtrlD.

Procedure 17.2: Emergency Shell: Rebuild the initrd

This fix is required if the multipath status (enabled or disabled) differs between initrd and system. To fix this, rebuild the initrd:

  1. If multipath has been enabled in the system, rebuild the initrd with multipath support with this command:

    dracut --force --add multipath

    In case Multipath has been disabled in the system, rebuild the initrd with Multipath support with this command:

    dracut --force -o multipath
  2. Exit the emergency shell and reboot the server by pressing CtrlD.

Procedure 17.3: Emergency Shell: Rebuild the initrd

This fix is required if the initrd does not contain drivers to access network attached storage. This may, for example, be the case when the system was installed without multipath or when the respective hardware was added or replaced.

  1. Add the required driver(s) to the variable force_drivers in the file /etc/dracut.conf.d/01-dist.conf. For example, if your system contains a RAID controller accessed by the hpsa driver and multipathed devices connected to a QLogic controller accessed by the driver qla23xx, this entry would look like:

    force_drivers+="hpsa qla23xx"
  2. Rebuild the initrd using the following command:

    dracut -f --add-multipath
  3. To prevent the system from booting into emergency mode if attaching the network storage fails, it is recommended to add the mount option _netdev to the respective entries in /etc/fstab.

  4. Exit the emergency shell and reboot the server by pressing CtrlD.

17.15.2 PRIO Settings for Individual Devices Fail After Upgrading to Multipath 0.4.9 or Later

Multipath Tools from version 0.4.9 onward uses the prio setting in the defaults{} or devices{} section of the /etc/multipath.conf file. It silently ignores the keyword prio when it is specified for an individual multipath definition in the multipaths{) section.

Multipath Tools 0.4.8 allowed the prio setting in the individual multipath definition in the multipaths{) section to override the prio settings in the defaults{} or devices{} section.

17.15.3 PRIO Settings with Arguments Fail After Upgrading to multipath-tools-0.4.9 or Later

When you upgrade from multipath-tools-0.4.8 to multipath-tools-0.4.9, the prio settings in the /etc/multipath.conf file are broken for prioritizers that require an argument. In multipath-tools-0.4.9, the prio keyword is used to specify the prioritizer, and the prio_args keyword is used to specify the argument for prioritizers that require an argument. Previously, both the prioritizer and its argument were specified on the same prio line.

For example, in multipath-tools-0.4.8, the following line was used to specify a prioritizer and its arguments on the same line.

prio "weightedpath hbtl [1,3]:.:.+:.+ 260 [0,2]:.:.+:.+ 20"

After upgrading to multipath-tools-0.4.9 or later, the command causes an error. The message is similar to the following:

<Month day hh:mm:ss> | Prioritizer 'weightedpath hbtl [1,3]:.:.+:.+ 260
[0,2]:.:.+:.+ 20' not found in /lib64/multipath

To resolve this problem, use a text editor to modify the prio line in the /etc/multipath.conf file. Create two lines with the prioritizer specified on the prio line, and the prioritizer argument specified on the prio_args line below it:

prio "weightedpath"
prio_args "hbtl [1,3]:.:.+:.+ 260 [0,2]:.:.+:.+ 20"

Restart the multipathd daemon for the changes to become active by running sudo systemctl restart multipathd.

17.15.4 Technical Information Documents

For information about troubleshooting multipath I/O issues on SUSE Linux Enterprise Server, see the following Technical Information Documents (TIDs) in the SUSE Knowledgebase:

18 Managing Access Control Lists over NFSv4

  • Filename: storage_nfs-acl.xml
  • ID: cha.nfs4_acls

There is no single standard for Access Control Lists (ACLs) in Linux beyond the simple read, write, and execute (rwx) flags for user, group, and others (ugo). One option for finer control is the Draft POSIX ACLs, which were never formally standardized by POSIX. Another is the NFSv4 ACLs, which were designed to be part of the NFSv4 network file system with the goal of making something that provided reasonable compatibility between POSIX systems on Linux and WIN32 systems on Microsoft Windows.

NFSv4 ACLs are not sufficient to correctly implement Draft POSIX ACLs so no attempt has been made to map ACL accesses on an NFSv4 client (such as using setfacl).

When using NFSv4, Draft POSIX ACLs cannot be used even in emulation and NFSv4 ACLs need to be used directly; that means while setfacl can work on NFSv3, it cannot work on NFSv4. To allow NFSv4 ACLs to be used on an NFSv4 file system, SUSE Linux Enterprise Server provides the nfs4-acl-tools package, which contains the following:

  • nfs4-getfacl

  • nfs4-setfacl

  • nfs4-editacl

These operate in a generally similar way to getfacl and setfacl for examining and modifying NFSv4 ACLs. These commands are effective only if the file system on the NFS server provides full support for NFSv4 ACLs. Any limitation imposed by the server will affect programs running on the client in that some particular combinations of Access Control Entries (ACEs) might not be possible.

It is not supported to mount NFS volumes locally on the exporting NFS server.

Additional Information

For information, see Introduction to NFSv4 ACLs at http://wiki.linux-nfs.org/wiki/index.php/ACLs#Introduction_to_NFSv4_ACLs.

A Documentation Updates

  • Filename: storage_docupdates.xml
  • ID: app.storage.docupdates

This chapter lists content changes for this document.

This manual was updated on the following dates:

A.1 March 2018

General

A.2 December 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)

General
General Updates
Bugfixes

A.3 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)

General
Chapter 1, Overview of File Systems in Linux
Chapter 14, Mass Storage over IP Networks: iSCSI
Chapter 17, Managing Multipath I/O for Devices
Chapter 17, Managing Multipath I/O for Devices

A.4 April 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP2)

Chapter 17, Managing Multipath I/O for Devices

A.5 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)

General
  • The e-mail address for documentation feedback has changed to doc-team@suse.com.

  • The documentation for Docker has been enhanced and renamed to Docker Guide.

General Changes to this Guide
Chapter 1, Overview of File Systems in Linux
Chapter 5, LVM Configuration
Chapter 14, Mass Storage over IP Networks: iSCSI
Bugfixes

A.6 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)

General
  • SMT Guide is now part of the documentation for SUSE Linux Enterprise Server.

  • Add-ons provided by SUSE have been renamed as modules and extensions. The manuals have been updated to reflect this change.

  • Numerous small fixes and additions to the documentation, based on technical feedback.

  • The registration service has been changed from Novell Customer Center to SUSE Customer Center.

  • In YaST, you will now reach Network Settings via the System group. Network Devices is gone (https://bugzilla.suse.com/show_bug.cgi?id=867809).

Chapter 1, Overview of File Systems in Linux
Chapter 5, LVM Configuration
Chapter 7, Software RAID Configuration
Chapter 13, iSNS for Linux
Chapter 17, Managing Multipath I/O for Devices
Bugfixes

A.7 February 2015 (Documentation Maintenance Update)

General
  • Completely restructured the manual by introducing parts.

  • Completely revised the complete guide.

  • Shortened the majority of procedures.

  • The cciss driver has been replaced with the hpsa driver. Changed all affected paragraphs accordingly (Fate #316683).

Chapter 1, Overview of File Systems in Linux
Chapter 2, Resizing File Systems
Chapter 5, LVM Configuration
Chapter 7, Software RAID Configuration
Chapter 9, Creating Software RAID 10 Devices
Chapter 13, iSNS for Linux
  • Removed all discovery domain set content, since this is no longer supported by open-isns.

Chapter 14, Mass Storage over IP Networks: iSCSI
  • Replaced iSCSI Target with iSCSI LIO Target.

Chapter 17, Managing Multipath I/O for Devices
Bugfixes

A.8 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)

General
  • Removed all KDE documentation and references because KDE is no longer shipped.

  • Removed all references to SuSEconfig, which is no longer supported (Fate #100011).

  • Move from System V init to systemd (Fate #310421). Updated affected parts of the documentation.

  • YaST Runlevel Editor has changed to Services Manager (Fate #312568). Updated affected parts of the documentation.

  • Removed all references to ISDN support, as ISDN support has been removed (Fate #314594).

  • Removed all references to the YaST DSL module as it is no longer shipped (Fate #316264).

  • Removed all references to the YaST Modem module as it is no longer shipped (Fate #316264).

  • Btrfs has become the default file system for the root partition (Fate #315901). Updated affected parts of the documentation.

  • The dmesg now provides human-readable time stamps in ctime()-like format (Fate #316056). Updated affected parts of the documentation.

  • syslog and syslog-ng have been replaced by rsyslog (Fate #316175). Updated affected parts of the documentation.

  • MariaDB is now shipped as the relational database instead of MySQL (Fate #313595). Updated affected parts of the documentation.

  • SUSE-related products are no longer available from http://download.novell.com but from http://download.suse.com. Adjusted links accordingly.

  • Novell Customer Center has been replaced with SUSE Customer Center. Updated affected parts of the documentation.

  • /var/run is mounted as tmpfs (Fate #303793). Updated affected parts of the documentation.

  • The following architectures are no longer supported: IA64 and x86. Updated affected parts of the documentation.

  • The traditional method for setting up the network with ifconfig has been replaced by wicked. Updated affected parts of the documentation.

  • A lot of networking commands are deprecated and have been replaced by newer commands (usually ip). Updated affected parts of the documentation.

    arp: ip neighbor
    ifconfig: ip addr, ip link
    iptunnel: ip tunnel
    iwconfig: iw
    nameif: ip link, ifrename
    netstat: ss, ip route, ip -s link, ip maddr
    route: ip route
  • Numerous small fixes and additions to the documentation, based on technical feedback.

SUSE Linux Enterprise Server 12 SP3

Security and Hardening Guide

Deals with the particulars of installing and setting up a secure SUSE Linux Enterprise Server, and additional post-installation processes required to further secure and harden that installation. Supports the administrator with security-related choices and decisions.

Publication Date: April 04, 2018
About This Guide
Assumptions and Scope
Contents of this Book
Available Documentation
Feedback
Documentation Conventions
I Common Criteria
1 Overview and rationale
1.1 What is the Common Criteria Certification?
1.2 Generic Guiding Principles
II General System Security and Service Protection Methods
2 Introduction
3 Linux Security in General
3.1 Physical Security
3.2 Locking Down the BIOS
3.3 Security via the Boot Loaders
3.4 Verifying Security Action with seccheck
3.5 Retiring Linux Servers with Sensitive Data
3.6 Backups
3.7 Disk Partitions
3.8 Firewall (iptables)
3.9 Security Features in the Kernel
3.10 AppArmor
3.11 SELinux
3.12 FTP, telnet, and rlogin (rsh)
3.13 Removing Unnecessary Software Packages (RPMs)
3.14 Patching Linux Systems
3.15 Securing the Network—Open Network Ports Detection
3.16 xinetd Services - Disabling
3.17 Securing Postfix
3.18 File Systems: Securing NFS
3.19 Copying Files Using SSH Without Providing Login Prompts
3.20 Checking File Permissions and Ownership
3.21 Default umask
3.22 SUID/SGID Files
3.23 World-Writable Files
3.24 Orphaned or Unowned Files
3.25 Restricting Access to Removable Media
3.26 Various Account Checks
3.27 Enabling Password Aging
3.28 Stronger Password Enforcement
3.29 Leveraging an Effective PAM stack
3.30 Preventing Accidental Denial of Service
3.31 Displaying Login Banners
3.32 Miscellaneous
A Documentation Updates
A.1 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)
A.2 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)
A.3 February 2015 (Documentation Maintenance Update)
A.4 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)

Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

About This Guide

The SUSE Linux Enterprise Server Security and Hardening Guide deals with the particulars of installation and set up of a secure SUSE Linux Enterprise Server and additional post-install processes required to further secure and harden that installation. Security and hardening elements and procedures are best applied to a server both during installation and post-installation and aim to improve the fitness of the system for the purposes demanded by its administrator.

This guide supports administrator in making security related choices and decisions. The individual steps and procedures should be seen as proposals, not as strict rules. You will often need to evaluate the usefulness of measures for your organization yourself.

The objective is to improve the security value of the system. Definitions about the meaning of the term security vary, but we want to settle on one that is both simple and abstract:

A good system does what it is expected to do, and it does it well.

A secure system is a good system that does nothing else.

The focus of this guide lies on doing nothing else. The Linux system is constructed in such way that security policies are enforced. These policies consist of the following concepts (fairly generic and incomplete list):

  • DAC (Discretionary Access Control): File and directory permissions, as set by chmod and chown.

  • Privileged ports: TCP and UDP ports 0-1023 and raw sockets can only be used by root.

  • Other privileged operations: Loading kernel modules, configuring network interfaces, all security relevant settings of the Linux kernel. These are operations that can only be done by the root user, that is the user with the user ID 0, or any other process with the necessary capabilities.

Attacking a system means to attempt to overcome privilege boundaries, for example by circumventing or breaking them. That means the administrator or programmer of the system has not anticipated this scenario.

A hardened system raises the bar by reducing the area that the system exposes to the attacker (often called attack surface). A hardened system can also provide measures to reduce the impact of vulnerabilities in the parts of the systems that must be exposed to a potential attacker.

Security is about decisions, and whenever security is in (apparent) opposition to function, these decisions become trade-offs. While it can be argued that all systems should be set up to be as securely as possible, some levels of security and hardening may very well be overkill in some cases. Each system's operational environment has its own security requirements derived from business drivers or regulatory compliance mandates. SUSE Linux Enterprise Server can, for example, be configured to comply with security standards, such as SOX, HIPAA and PCIDSS. It can also be set up to fulfill the requirements from the German Federal Office of Information Security (Bundesamt für Sicherheit in der Informationstechnik) as described in BSI TR-02102-1. An effective business requirements analysis should be performed to determine the right level of security and hardening to be applied to a server or defined as part of a baseline server build.

As a final note before we begin: You may encounter individual requirements in regulatory compliance frameworks that may not make sense from a technical perspective, or they do not serve the purpose of improving security. It may be a productive attitude to simply implement what is required, but whenever there is a contradiction to security, an informed discussion in the documentation serves the overall purpose of your regulative compliance framework much more than blindly obeying the specifications. Feel encouraged to dispute list items that you think are counterproductive.

1 Assumptions and Scope

References in this document will usually be made to a single server target or host, however the scope can generally be applied to more than one machine. We generally assume that the security target can cover one or more systems running SUSE Linux Enterprise Server.

We explicitly do not make any assumptions about the hostility of the network that the systems are connected to, or the cooperative nature of the users that leverage the services provided by the systems.

In turn, this means that you partially define your context on your own when reading through this document. You will need to broaden the meaning of individual portions to adapt it to your environment. In some cases, such as the use case of a server that is exposed to the Internet, this document may even be insufficient or incomplete; however, it may still serve as a good starting point on your journey toward an increased level of confidence that your system will behave like you want it to.

About trust: Trust relationships exist among all systems that participate in networked transactions. In this way, the trust relationship between the people that use the systems is transported across these systems. The chain that is formed by your trust relationships is only as strong as the weakest link. It is good practice to graphically visualize the trust relationships with the services in a schematic overview or map of your network. Generally, it is up to the owner of a resource to enforce the policies imposed on that resource; this would usually be the server that provides the resource. The client that opens a connection to request the resource can only be made responsible for the actions that it performs. This refers to the action of opening the connection to start with, but to nothing else as such.

The case of hostile users is special and unique: The Human Resources department may be able to solve some security problems in your computing environment; in addition, some technical measures can be taken. Make sure that the necessary regulations in your environment fit your needs, and that they back your intentions instead of obstructing them if you need to work around a missing support from your HR department (and your management).

Persons that have administrative privileges on a system are automatically considered trusted.

A Linux system—without any additional security frameworks such as SELinux—is a single level security system: From a security policy perspective there is only the superuser (root) and non-privileged users. System users are non-root user IDs that have access to files specific to their purpose. The separation of administrative duties is complicated by this simplicity. Some tools help: Use sudo(8) for administrative tasks, but be aware that after the privilege boundary is crossed, a program running with root privileges does not enforce any file access policies for non-privileged users anymore. vi(1) that runs as root can read and write to any file in the system.

Another tool to mitigate the risk of abuse or accidental misuse of administrative privileges is NetIQ's Privileged User Manager product. More information is available here:

Physical security of the server is another assumption made here, where the server is protected from theft and manipulation by unauthorized persons. A common sobering thought among security professionals is the ten-second Denial of Service: Unplug the wires and reboot the server. Physical security must be ensured and physical access must be controlled. Otherwise, all assumptions about at least the availability of these systems are void.

Note
Note: Cryptography

The use of cryptography to protect the confidentiality of transactions with the services that your system provides is generally encouraged. The need to implement cryptographic enhancements is strongly dependent on the operational environments of all participating systems. Keep in mind that you need to verify all of the possible security benefits that cryptography can provide, for all of your services, and that these benefits are not delivered automatically by turning on the encrypt option of your service (if you can enjoy the idyllic situation where encryption is available as a button to check):

Confidentiality

Protection against reading the content of a transaction

Privacy

Protection against knowing that a transaction exists, and some properties that it may have, such as size, identities of involved parties, their presence, etc.

Integrity

Protection against alteration of content. Be aware that cryptography does not automatically provide this kind of protection.

Authenticity

Protection against identity fraud. Cryptography that does not know about identities of participating entities cannot deliver this value.

Keep in mind that encryption of data for confidentiality purposes can merely reduce the size of the data to protect from the actual size to the size of the key that is used to encrypt the data. This results in a key exchange problem for encrypted transactions, and in a key management problem for encrypted data storage. Since data is (typically, there are exceptions!) processed in clear, you need your vault unlocked while data within is being worked with. The encryption of such data on the file system or block device layer helps against the theft of the system, but it does not help the confidentiality of the data while the system is running.

If you want to implement a consistent security policy covering multiple hosts on a network then organizational procedures must ensure that all those hosts can be trusted and are configured with compatible security configurations enforcing an organization wide security policy. Isolation of groups of systems that maintain data of the same trust domain can provide an adequate means of control; ultimately, the access controls to these systems, both for end users and for other systems, need to be carefully designed, configured, inspected and monitored.

Important
Important: Trusting Data

Data can only be trusted to the degree that is associated with the domain it comes from. If data leaves the domain in which security policies can be enforced, it should consequently be associated with the trust of the target domain.

For a review of industry best practices on security, the development of sound security processes, controls, development, reviews, audit practices and incident management, you can review a public RFC (request for comments). RFC 2196 is the ongoing work of the world-wide community and individual security and process experts. You can review it online here: http://www.faqs.org/rfcs/rfc2196.html. An RFC is an open and living document that invites comments and review. Enhancements and improvements are welcome; you will find instructions on where to send those suggestions within the document itself.

This guide provides initial guidance on how to set up and secure a SUSE Linux Enterprise Server installation but it is not intended to be the only information required for a system administrator to learn how to operate Linux securely. Assumptions are made within this guide that the reader has knowledge and understanding of operating security principles in general, and of Linux administrative commands and configuration options in particular.

2 Contents of this Book

Part I, “Common Criteria” contains a reference to Common Criteria and SUSE Linux Enterprise Server. Part II, “General System Security and Service Protection Methods” contains more general system security and service protection schemes.

3 Available Documentation

  • Filename: common_intro_available_doc_i.xml
  • ID: no ID found
Note
Note: Online Documentation and Latest Updates

Documentation for our products is available at http://www.suse.com/documentation/, where you can also find the latest updates, and browse or download the documentation in various formats.

In addition, the product documentation is usually available in your installed system under /usr/share/doc/manual.

The following documentation is available for this product:

Installation Quick Start

Lists the system requirements and guides you step-by-step through the installation of SUSE Linux Enterprise Server from DVD, or from an ISO image.

Deployment Guide

Shows how to install single or multiple systems and how to exploit the product inherent capabilities for a deployment infrastructure. Choose from various approaches, ranging from a local installation or a network installation server to a mass deployment using a remote-controlled, highly-customized, and automated installation technique.

Administration Guide

Covers system administration tasks like maintaining, monitoring and customizing an initially installed system.

Virtualization Guide

Describes virtualization technology in general, and introduces libvirt—the unified interface to virtualization—and detailed information on specific hypervisors.

Storage Administration Guide

Provides information about how to manage storage devices on a SUSE Linux Enterprise Server.

AutoYaST

AutoYaST is a system for unattended mass deployment SUSE Linux Enterprise Server systems using an AutoYaST profile containing installation and configuration data. The manual guides you through the basic steps of auto-installation: preparation, installation, and configuration.

Security Guide

Introduces basic concepts of system security, covering both local and network security aspects. Shows how to use the product inherent security software like AppArmor or the auditing system that reliably collects information about any security-relevant events.

Security and Hardening Guide

Deals with the particulars of installing and setting up a secure SUSE Linux Enterprise Server, and additional post-installation processes required to further secure and harden that installation. Supports the administrator with security-related choices and decisions.

System Analysis and Tuning Guide

An administrator's guide for problem detection, resolution and optimization. Find how to inspect and optimize your system by means of monitoring tools and how to efficiently manage resources. Also contains an overview of common problems and solutions and of additional help and documentation resources.

SMT Guide

An administrator's guide to Subscription Management Tool—a proxy system for SUSE Customer Center with repository and registration targets. Learn how to install and configure a local SMT server, mirror and manage repositories, manage client machines, and configure clients to use SMT.

GNOME User Guide

Introduces the GNOME desktop of SUSE Linux Enterprise Server. It guides you through using and configuring the desktop and helps you perform key tasks. It is intended mainly for end users who want to make efficient use of GNOME as their default desktop.

4 Feedback

  • Filename: common_intro_feedback_i.xml
  • ID: no ID found

Several feedback channels are available:

Bugs and Enhancement Requests

For services and support options available for your product, refer to http://www.suse.com/support/.

Help for openSUSE is provided by the community. Refer to https://en.opensuse.org/Portal:Support for more information.

To report bugs for a product component, go to https://scc.suse.com/support/requests, log in, and click Create New.

User Comments

We want to hear your comments about and suggestions for this manual and the other documentation included with this product. Use the User Comments feature at the bottom of each page in the online documentation or go to http://www.suse.com/documentation/feedback.html and enter your comments there.

Mail

For feedback on the documentation of this product, you can also send a mail to doc-team@suse.com. Make sure to include the document title, the product version and the publication date of the documentation. To report errors or suggest enhancements, provide a concise description of the problem and refer to the respective section number and page (or URL).

5 Documentation Conventions

  • Filename: common_intro_typografie_i.xml
  • ID: no ID found

The following notices and typographical conventions are used in this documentation:

  • /etc/passwd: directory names and file names

  • PLACEHOLDER: replace PLACEHOLDER with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • package name : name of a package

  • Alt, AltF1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File › Save As: menu items, buttons

  • x86_64 This paragraph is only relevant for the AMD64/Intel 64 architecture. The arrows mark the beginning and the end of the text block.

    System z, POWER This paragraph is only relevant for the architectures z Systems and POWER. The arrows mark the beginning and the end of the text block.

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

  • Commands that must be run with root privileges. Often you can also prefix these commands with the sudo command to run them as non-privileged user.

    root # command
    tux > sudo command
  • Commands that can be run by non-privileged users.

    tux > command
  • Notices

    Warning
    Warning: Warning Notice

    Vital information you must be aware of before proceeding. Warns you about security issues, potential loss of data, damage to hardware, or physical hazards.

    Important
    Important: Important Notice

    Important information you should be aware of before proceeding.

    Note
    Note: Note Notice

    Additional information, for example about differences in software versions.

    Tip
    Tip: Tip Notice

    Helpful information, like a guideline or a piece of practical advice.

Part I Common Criteria

1 Overview and rationale

Abstract

1.1 What is the Common Criteria Certification?

Common Criteria is the best known and most widely used methodology to evaluate and measure the security value of an IT product. The methodology aims to be independent, as an independent laboratory conducts the evaluation, which a certification body will certify afterward. Security Functional Requirements (SFR) are summarized in so-called Protection Profiles (PP), which allows the comparison of security functions of different products if the definition of the Security Target (ST) (which typically uses a reference to the PP if one exists that fits the purpose of the product) and the Evaluation Assurance Levels are comparable.

A clear definition of security in IT products is challenging. Security should be considered a process that never ends, not a static condition that can be met or not. A Common Criteria certificate (below EA7) does not make a clear statement about error proneness of the system (while many of the flaws that exist specifically in operating systems are security-relevant), but it adds an important value to the product that cannot be described with the presence of technology alone: That someone has independently inspected the design of the system in such way that it corresponds to the claims that are made, and that explicit care has been taken in producing and maintaining the product.

The certificate states a degree of maturity of both the product with its security functions and the processes of the company that has designed, built and engineered the product, and that will maintain the product across its life cycle. As such, Common Criteria aims to be fairly holistic with its approach to take everything into account that is relevant for the security of an IT product.

The Evaluation Assurance Level (EAL) shall denote the degree of confidence that the product fulfills the described claims. The levels are from 1 through 7:

  • EAL1: Functionally tested

  • EAL2: Structurally tested

  • EAL3: Methodically tested and checked

  • EAL4: Methodically designed, tested and reviewed

  • EAL5: Semi-formally designed and tested

  • EAL6: Semi-formally verified design and tested

  • EAL7: Formally verified design and tested

While EAL1 only provides basic assurance for products to meet security requirements, EAL2 to 4 are medium assurance levels. EAL5-EAL7 describe medium-to-high and high assurance; EAL4 is expected to be the highest level of assurance that a product can have if it has not been designed from the start to achieve a higher level of assurance.

Many commonly known General Purpose/Utility Computing operating systems have been awarded a Common Criteria certificate at EAL4. A "+" after the assurance level denotes an augmentation to the EAL, an addition that is useful for the articulation of security value, but formally not needed at the corresponding EAL.

The SUSE Linux Enterprise Server version 8 was the first Linux system to achieve EAL3+ (Augmentation: Basic Flaw Remediation) in 2003; Version 9 of SLES was the first Linux based operating system to reach EAL4+ in 2004. More certifications and re-certifications have followed targeting SLES 9 and SLES 10-SP1, until the SUSE Linux Enterprise Server version Service Pack 2 was evaluated in 2011/2012.

The Common Criteria evaluations inspect a specific configuration of the product in an evaluated setup. The Administrator's Guide is a document that comes with a Common Criteria certified product and describes the individual steps that need to be taken to install and configure the product to a state like it was evaluated.

Very often, the evaluated configuration is used as a reference for the secure installation of the SUSE Linux Enterprise Server. It is however incorrect to understand the evaluated configuration as a hardened configuration: the removal of setuid bits and the prescription of administrative procedures after installation is there to reach a specific configuration that is sane, but this process is clearly insufficient for a hardening claim.

Earlier versions of this document have contained a substantial part that links to Common Criteria evaluated configurations. For clarity and to avoid confusion these chapters have been removed.

Instead, this guide recommends the lecture the documentation that comes with the Common Criteria certificate to understand the Common Criteria evaluation of SUSE Linux Enterprise Server in general, the security functions that are in place within the operating system and how these security functions are relevant for the mitigation of threats. The High Level Design documentation encompasses the design specifics of the SUSE Linux Enterprise Server: Authentication mechanisms, access controls, audit subsystem and system log files, to name a few of them. The accumulated knowledge contained in the documentation allows decision making for hardening purposes at an informed level—find it at http://www.suse.com/security/.

Apart from the valuable documentation that comes with the Common Criteria effort, the following manual pages may be of greater interest to the inclined reader:

pam(8), pam(5)

apparmor(7) and referred man pages

rsyslogd(8), syslog(8), syslogd(8)

fstab(5), mount(8), losetup(8), cryptsetup(8)

haveged(8), random(4)

ssh(1), sshd(8), ssh_config(5), sshd_config(5), ssh-agent(1), ssh-add(1), ssh-keygen(1)

cron(1), crontab(5), at(1), atd(8)

systemctl(1), daemon(7), systemd.unit(5), systemd.special(5), kernel-command-line(7), bootup(7), systemd.directives

1.2 Generic Guiding Principles

The following guiding principles motivate much of the advice in this guide, and security processes in general, and should also influence any configuration decisions that are not explicitly covered.

Use Data Encryption Whenever Possible

Refer to the About This Guide section of this guide. In Section 1, “Assumptions and Scope”, the limitations of cryptography are briefly outlined.

Be aware that cryptography is certainly useful, but only for the specific purposes that it is good for. It is not a generic recipe for better security in a system, its use may even impose additional risk on the system. Make informed decisions about the use of cryptography, and feel obliged to have a reason for your decisions, no matter if they are for or against cryptography. A false sense of security can be more harmful than the weakness itself. SUSE Linux Enterprise Server supports encryption for generic network connections (the openssl command, stunnel), for remote login (openssh, man ssh(1)), for generic file encryption (gpg), for entire file systems at block layer (dm_crypt, cryptsetup) and for VPN (iipsec, openvpn).

Minimal Package Installation

Generally, an RPM software package consists of the package's meta data that is written to the RPM database upon installation, the package's files and directories and scripts that are being executed before and after installation and removal.

If the package does NOT contain

  1. setuid- or setgid bits on any of the installed files

  2. group- or world-writable files or directories

  3. a service that is activated upon installation/activated by default.

then the said package generally does not impose any security risk to the system. Under the above condition, the package is merely a collection of files, and their use shall not be automatically assumed if you do not have any local users on your system. Since the installation of such packages does not have any influence on the security value of the system, the uninstallation of them should not either.

However, a fairly simple reason to keep to a minimal set of packages in your installation is that something that is not present cannot get used. Binaries not installed cannot be executed.

A straight forward way of keeping to a minimal set of packages begins with the installation of the system. You can start the installation of your system by deselecting all packages and then select only those that you want to use. As an example, the selection of the apache2-mod_perl package in YaST would automatically cause all packages to be selected for installation that are needed for the Apache package to operate. Dependencies have often been artificially cut down to be able to handle the system's dependency tree more flexibly. You should be safe if you chose the minimal system, and build the dependency tree from there with your (leaf) package selection.

Service Isolation—Run Different Services on Separate Systems

Whenever possible, a server should be dedicated to serving exactly one service or application. This limits the number of other services that could be compromised in the event an attacker can successfully exploit a software flaw in one service (assuming that flaw allows access to others).

This point can lead to healthy and robust dialog on system sizing and even further to consolidation or virtualization. The intent with this guidance is to reduce the fault domain and risk where possible.

The use of AppArmor for services that are provided on a system is an effective means of containment. Refer to the AppArmor documentation on your system to learn more. man apparmor is a good starting point.

The use of virtualization technology with KVM or with Xen is supported with the SUSE Linux Enterprise Server version 12 SP3. While virtualization is generally designed for server consolidation purposes, its usefulness for service isolation is another good argument. Be aware that the capability of the hypervisor to separate virtual machines is not higher or stronger than the Linux kernel's capability to separate processes and their address spaces. The granularity at which virtualization technology tackles separation may however come with its benefits, being resource-hungry and somewhat clumsy on the other hand.

Note
Note

Virtualization technology cannot match or substitute the separation strength that is given by running services on different physical machines!

System fingerprinting and backups

In the case of the suspicion of an attack against the system, nothing can provide more comfort than

  1. a backup

  2. a fingerprint of your system to detect modifications

  3. having done your homework.

Several tools exist on SUSE Linux Enterprise Server 12 SP3 which can be effectively used for the detection of unknown, but yet successful attacks. These tools come at the cost of relatively little configuration effort, but with the benefit of being able to actually know what has been changed in your system.

In particular, the use of AIDE is strongly encouraged. AIDE, when run for initialization, creates a hash database of all files in the system that are listed in its configuration file. This allows to verify the integrity of all cataloged files at a later time.

Note
Note

You need to copy the hash database that AIDE creates to a place that is inaccessible for potential attackers. Otherwise, the attacker may modify the integrity database after planting a backdoor, thereby defeating the purpose of the integrity measurement.

Note
Note

An attacker may have planted a backdoor in the kernel. This has an entire variety of consequences: Apart from being very hard to detect, the kernel-based backdoor can effectively remove all traces of the system compromise to the degree that system alterations are almost invisible. By consequence, an integrity check needs to be done from a rescue system (or any other system where an independent system runs, and the target system's file systems are mounted manually).

Note
Note

Security is a lively process. Essentially, in this context, this means that the application of security updates invalidates the integrity database. rpm -qlv packagename lists the files that are contained in a package. Generally spoken, the RPM subsystem is very powerful with the data that it maintains, and that is accessible with the --queryformat command line option. A differential update of integrity database with the changed files becomes more manageable with some fine-grained usage of RPM.

A fast and directly accessible backup adds distinct confidence about the integrity of your system and can substitute an integrity check such as described above with AIDE. It is important, though, that the backup mechanism/solution has adequate versioning support so that you can trace changes in the system. As an example: The installation times of packages (rpm -q --queryformat='%{INSTALLTIME} %{NAME}\n' PACKAGE NAME) must correspond to the changed files in the backup log files.

Note
Note

Make it an integral part of your security routine to verify that your backups work.

Part II General System Security and Service Protection Methods

2 Introduction

In Part I, “Common Criteria” we mentioned the Common Criteria EAL 4+ certified installation and setup that was sponsored by IBM for a select subset of hardware. This certified build is a great first step for customers wanting to build a secure and hardened base system, yet might not address all of t…

3 Linux Security in General

This portion of the guide will only give basic recommendations instead of strict rules. The procedures and examples here should give you the ability to apply security enhancement techniques to a wider variety of server-based services and programs.

2 Introduction

In Part I, “Common Criteria” we mentioned the Common Criteria EAL 4+ certified installation and setup that was sponsored by IBM for a select subset of hardware. This certified build is a great first step for customers wanting to build a secure and hardened base system, yet might not address all of the services and software specifics that many customers would be interested in.

This next part will present a more general view and give recommendations and guidance for SUSE Linux Enterprise Server system security. Some topics may seem repeated here (from the previous part) yet the context is very different. More detail will be provided in some sections and certainly some more general examples for a greater number of services.

3 Linux Security in General

This portion of the guide will only give basic recommendations instead of strict rules. The procedures and examples here should give you the ability to apply security enhancement techniques to a wider variety of server-based services and programs.

Some subjects of this chapter have been discussed before. However, you will find more details and explanations in this chapter. Selected general topics are:

  • Physical Security – Protection of the server from environmental threats (people, places, things).

  • Security Policies and Procedures – Server life cycle management, disk/media reclamation, backup and archive security.

  • Systems Monitoring – Procedures around event notification/management.

  • Systems Automation – Mechanisms and/or procedures for automatic security measures. Heuristics, account control, security reporting and remediation, automated shutdown, etc.

  • Systems Management – Methods to obtaining packages, verification and signing keys, patching procedures and recommendations.

  • Securing Network – Addition programs, ports and service wrappers – iptables, tcpwrappers, services.

  • Remote Access – extra SSH information and key federation. CA integration.

  • Common Services – mail, NFS and automount.

  • Securing the kernel and Init Process – parameters, systemd targets, and boot scripts.

  • Access Control – user/groups/permissions.

  • Password Security and Warnings – Proper setup of passwords, banners and xinetd.

  • Miscellaneous Security – Assorted security settings and miscellany.

  • Resources – Web links, documentation and example references, howtos and general information, product links.

The sections will again be organized by a topical hierarchy for continuity-sake. Refer to the main table of contents for easy reference.

3.1 Physical Security

Physical security should be one of the utmost concerns. Linux production servers should be in locked data centers where only people have access that have passed security checks. Depending on the environment and circumstances, you can also consider boot loader passwords.

Additionally, consider questions like:

  • Who has direct physical access to the host?

  • Of those that do, should they?

  • Can the host be protected from tampering and should it be?

The amount of physical security needed on a particular system depends on the situation, and can also vary widely by available funds.

3.1.1 System Locks

Most server racks in data centers include a locking feature. Usually this will be a hasp/cylinder lock on the front of the rack that allows you to turn an included key to a locked or unlocked position – granting or denying entry. Cage locks can help prevent someone from tampering or stealing devices/media from the servers, or opening the cases and directly manipulating/sabotaging the hardware. Preventing system reboots or the booting from alternate devices is also important (for example CD/DVDs/USB drives/etc.).

Some servers also have case locks. These locks can do different things according to the designs of the system vendor and construction. Many systems are designed to self-disable if attempts are made to open the system without unlocking. Others have device covers that will not let you plug in or unplug keyboards or mice. While locks are sometimes a useful feature, they are usually lower quality and easily defeated by attackers with ill intent.

3.2 Locking Down the BIOS

Tip
Tip: Secure Boot

This section describes only basic methods to secure the boot process. To find out more about UEFI and the secure boot feature, see Section 11.1, “Secure Boot”.

The BIOS (Basic Input/Output System) or its successor UEFI (Unified Extensible Firmware Interface) is the lowest level of software/firmware that dictates system configuration and low-level hardware. When this document references the BIOS, it usually means BIOS and/or UEFI. GRUB 2 and other Linux boot loaders access the BIOS to determine how to boot the host. Other hardware types (POWER/z Systems) that run Linux also have low-level software/firmware. Typically the BIOS can be configured to help prevent attackers from being able to reboot the host and manipulate the system.

Most BIOS varieties allow the setting of a boot password. While this does not provide a high level of security (a BIOS can be reset, removed or modified – assuming case access), it can be another deterrent.

Many BIOS capabilities have other various security settings – checking with the system vendor, the system documentation or examine the BIOS during a system boot.

Important
Important: Booting when a BIOS Password is Set

If a system host has been set up with a boot password, the host will not boot up unattended (for example a system reboot, power failure, etc.). This is a trade-off.

3.3 Security via the Boot Loaders

The Linux boot loader GRUB 2, which is used by default in SUSE Linux Enterprise Server, can have a boot passwords set. It also provides a password feature, so that only administrators can start the interactive operations (for example editing menu entries and entering the command line interface). If a password is specified, GRUB 2 will disallow any interactive control until you press the key C and E and enter a correct password.

You can refer to the GRUB 2 man page for examples.

It is very important to keep in mind that when setting these passwords they will need to be remembered! Also, enabling these passwords might merely slow an intrusion, not necessarily prevent it. Again, someone could boot from a removable device, and mount your root partition. If you are using BIOS-level security and a boot loader, it is a good practice to disable the ability to boot from removable devices in your computer's BIOS, and then also password-protecting the BIOS itself.

Also keep in mind that the boot loader configuration files will need to be protected by changing their mode to 600 (read/write for root only), or others will be able to read your passwords or hashes!

3.4 Verifying Security Action with seccheck

It is highly recommended to have scripts in place which can verify that security actions or procedures have been run. Even the best systems administrators can make errors or forget something. If you have a small or large Linux installation or environment, you should consider the use of the seccheck scripts.

seccheck is the SUSE Security Checker. It is a set of several shell scripts designed to check the local security of the system on a regular basis. There are three main scripts that are executed at different time intervals. They are security-daily, security-weekly and security-monthly. If seccheck is not installed on your system, install it with sudo zypper in seccheck. These scripts all have schedule entries that get placed in cron that determine when they run. Although cron scheduling is the default behavior, this can be controlled via configuration settings (see next section). The daily script runs at midnight, and if changes are detected since the last run (the night before), an e-mail noting the differences will be sent. The weekly script runs every Monday at 1:00 am, and only if changes to the last run (the week before) are found, a mail with the differences will be sent. The monthly script runs every on every 1st of the month and sends the full last daily and weekly report via e-mail.

3.4.1 Seccheck Configuration

Note that you can change the receiver of the seccheck mails from root to anyone else if you add an entry like this one to /etc/sysconfig/seccheck:

SECCHK_USER="firewall" # exchange firewall is an admin user's account name

Also note that the START_SECCHK variable from /etc/sysconfig/seccheck controls whether the security check will be run from cron. (It is ignored if you call security-control manually.)

The following daily checks are done:

/etc/passwd check

length/number/contents of fields, accounts with same uid accounts with uid/gid of 0 or 1 beside root and bin

/etc/shadow check

length/number/contents of fields, accounts with no password

/etc/group check

length/number/contents of fields

user root checks

secure umask and PATH

/etc/ftpusers

checks if important system users are put there

/etc/aliases

checks for mail aliases which execute programs

.rhosts check

checks if users' .rhosts file contain + signs

homedirectory

checks if home directories are writable or owned by someone else

dot-files check

checks many dot-files in the home directories if they are writable or owned by someone else

mailbox check

checks if user mailboxes are owned by user and are readable

NFS export check

exports should not be exported globally

NFS import check

NFS mounts should have the nosuid option set

promisc check

checks if network cards are in promiscuous mode

list modules

lists loaded modules

list sockets

lists open ports

Weekly Checks are as follows:

password check

runs john to crack the password file, user will get an e-mail notice to change his password

RPM md5 check

checks for changed files via RPM's MD5 checksum feature

suid/sgid check

lists all suid and sgid files

exec group write

lists all executables which are group/world-writable

writable check

lists all files which are world-writable (including executables)

device check

lists all devices

Additional monthly checks are also run, however the key difference is mainly that the monthly file is not a diff like the daily/weekly ones but the full reports in one file.

3.4.2 Automatic Logout

The seccheck package provides an automatic logout feature. It is a script that runs every 10 minutes and checks both remote or local terminal sessions for inactivity, and terminates them if an idle time is exceeded.

You can configure the functionality in the /etc/security/autologout.conf file. Parameters include default idle and logout delay times, and the configuration for limiting maximum idle times specific to users, groups, TTY devices and SSH sessions. /etc/security/autologout.conf also includes several configuration examples.

Tip
Tip

The automatic logout feature is not enabled by default. To enable it, edit /etc/cron.d/autologout and uncomment the example cron line.

3.5 Retiring Linux Servers with Sensitive Data

Security policies usually contain some procedures for the treatment of storage media that is going to be retired or disposed of. Disk and media wipe procedures are frequently prescribed as is complete destruction of the media. You can find several free tools on the Internet. A search of dod disk wipe utility will yield several variants. To retire servers with sensitive data, it is important to ensure that data cannot be recovered from the hard disks. To ensure that all traces of data are removed, a wipe utility—such as scrub—can be used. Many wipe utilities overwrite the data several times. This assures that even sophisticated methods are not able to retrieve any parts of the wiped data. Some tools can even be operated from a bootable removable device and remove data according to the U.S. Department of Defense (DoD) standards. Note that many government agencies specify their own standards for data security. Some standards are stronger than others, yet may require more time to implement.

Important
Important: Wiping Wear Leveling Devices

Some devices, like SSDs, use wear leveling and do not necessarily write new data in the same physical locations. Such devices usually provide their own erasing functionality.

3.5.1 scrub: Disk Overwrite Utility

scrub overwrites hard disks, files, and other devices with repeating patterns intended to make recovering data from these devices more difficult. It operates in three basic modes: on a character or block device, on a file, or on a directory specified. For more information, set the manual page man 1 scrub.

Supported Scrub Methods
nnsa

4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for sanitizing removable and non-removable hard disks, which requires overwriting all locations with a pseudo random pattern twice and then with a known pattern: ran- dom(x2), 0x00, verify.

dod

4-pass DoD 5220.22-M section 8-306 procedure (d) for sanitizing removable and non-removable rigid disks which requires overwriting all addressable locations with a character, its complement, a random character, then verify. NOTE: scrub performs the random pass first to make verification easier: random, 0x00, 0xff, verify.

bsi

9-pass method recommended by the German Center of Security in Information Technologies (http://www.bsi.bund.de): 0xff, 0xfe, 0xfd, 0xfb, 0xf7, 0xef, 0xdf, 0xbf, 0x7f.

gutmann

The canonical 35-pass sequence described in Gutmann's paper cited below.

schneier

7-pass method described by Bruce Schneier in "Applied Cryptography" (1996): 0x00, 0xff, random(x5)

pfitzner7

Roy Pfitzner's 7-random-pass method: random(x7).

pfitzner33

Roy Pfitzner's 33-random-pass method: random(x33).

usarmy

US Army AR380-19 method: 0x00, 0xff, random. (Note: identical to DoD 522.22-M section 8-306 procedure (e) for sanitizing magnetic core memory).

fillzero

1-pass pattern: 0x00.

fillff

1-pass pattern: 0xff.

random

1-pass pattern: random(x1).

random2

2-pass pattern: random(x2).

old

6-pass pre-version 1.7 scrub method: 0x00, 0xff, 0xaa, 0x00, 0x55, verify.

fastold

5-pass pattern: 0x00, 0xff, 0xaa, 0x55, verify.

custom=string

1-pass custom pattern. String may contain C-style numerical escapes: \nnn (octal) or \xnn (hex).

3.6 Backups

If your system is compromised, backups can be used to restore a prior system state. When bugs or accidents occur, backups can also be used to compare the current system against an older version. For production systems, it is very important to take some backups off-site for cases like disasters (for example off-site storage of tapes/recordable media, or off-site initiated).

For legal reasons, some firms and organizations must be careful about backing up too much information and holding it too long. If your environment has a policy regarding the destruction of old paper files, you might need to extend this policy to Linux backup tapes as well.

The rules about physical security of servers apply on backups as well.

3.7 Disk Partitions

Servers should have separate file systems for at least /, /boot, /usr, /var, /tmp, and /home. You do not want that for example logging and temporary space under /var and /tmp fill up the root partition. Third-party applications should be on separate file systems as well, for example under /opt.

You are advised to review Part I, “Common Criteria”. It is important to understand the need to separate the partitions that could impact a running system (for example, log files filling up /var/log are a good reason to separate /var from the / partition). Another thing to keep in mind is that you will likely need to leverage LVM or another volume manager or at the very least the extended partition type to work around the limitations of primary partitions (4 partitions).

Another capability in SUSE Linux Enterprise Server is encrypting a partition or even a single directory or file as a container. Refer to Chapter 11, Encrypting Partitions and Files for details.

3.8 Firewall (iptables)

iptables will not be covered in detail in this guide. Most companies use dedicated firewalls or appliances to protect their servers in a production network. This is strongly recommended for secure environments. SUSE Linux Enterprise Server also includes SuSEFirewall2 which is a wrapper for iptables and is enabled by default as a simple and layered protection.

If you are also interested in Linux stateful firewalls using iptables, there are many guides on the Internet. See the Appendix for resources. For lots of iptables tutorials and examples, see http://www.linuxguruz.com/iptables/.

3.9 Security Features in the Kernel

The following list shows tunable kernel parameters you can use to secure your Linux server against attacks. Some are defaults already within the SLE distributions. To check the current status of any of these settings, you can query the kernel (/proc/sys/... contents). For example, the Source Routing setting is located in the /proc/sys/net/ipv4/conf/all/accept_source_route file. Simply display the contents of a file to see how the current running kernel is set up.

For each tunable kernel parameter shown, the change to the entry that needs to be affected can be modified or added to the /etc/sysctl.conf configuration file to make the change persistent after a reboots.

You can get a list of current kernel settings by using the command:

root # sysctl -a

It is even a very good idea to store the output of the kernel settings (for comparison or reference) by redirecting the output of the sysctl command to a file, for example

root # sysctl -A > /root/sysctl.settings.store

Because SUSE Linux Enterprise Server includes, by default, security-focused kernel tuning parameters, you will find the existing /etc/sysctl.conf file to be sparsely populated. You may choose to use the above mentioned catalog method of storing the complete gamut of kernel settings and then choose those parameters you want to be reset at reboot. You can place these in the /etc/sysctl.conf file where they will be picked up upon a reboot or they can be inserted immediately (into the running kernel) by running the command sysctl -p.

Many third-party applications like Oracle, SAP, DB2, Websphere, etc. recommend changing kernel parameters to ensure high performance for I/O or CPU processing. Having a full list of current settings can be helpful for reference.

3.9.2 Disable IP Source Routing (default in SUSE Linux Enterprise Server 12 SP3)

Source Routing is used to specify a path or route through the network from source to destination. This feature can be used by network people for diagnosing problems. However, if an intruder was able to send a source routed packet into the network, then he could intercept the replies and your server might not know that it is not communicating with a trusted server.

net.ipv4.conf.all.accept_source_route = 0

or

net.ipv6.conf.all.accept_source_route = 0

3.9.3 Disable ICMP Redirect Acceptance

ICMP redirects are used by routers to tell the server that there is a better path to other networks than the one chosen by the server. However, an intruder could potentially use ICMP redirect packets to alter the host's routing table by causing traffic to use a path you did not intend. To disable ICMP Redirect Acceptance, edit the /etc/sysctl.conf file and add the following line:

net.ipv4.conf.all.accept_redirects = 0

or

net.ipv6.conf.all.accept_redirects = 0

3.9.4 Enable IP Spoofing Protection (default in SUSE Linux Enterprise Server 12 SP3)

IP spoofing is a technique where an intruder sends out packets which claim to be from another host by manipulating the source address. IP spoofing is very often used for denial of service attacks. For more information on IP Spoofing, see http://en.wikipedia.org/wiki/IP_address_spoofing

net.ipv4.conf.all.rp_filter = 1

3.9.5 Enable Ignoring to ICMP Requests

If you want or need Linux to ignore ping requests, edit the /etc/sysctl.conf file and add the following line:

net.ipv4.icmp_echo_ignore_all = 1

This cannot be done in many environments, as some monitoring systems use a rudimentary ICMP (ping) to determine the health of the device on the network (or at least its ability to respond).

3.9.6 Enable Ignoring Broadcasts Request (default in SUSE Linux Enterprise Server 12 SP3)

If you want or need Linux to ignore broadcast requests.

net.ipv4.icmp_echo_ignore_broadcasts = 1

3.9.7 Enable Bad Error Message Protection (default in SUSE Linux Enterprise Server 12 SP3)

To alert you about bad error messages in the network.

net.ipv4.icmp_ignore_bogus_error_responses = 1

3.9.8 Enable Logging of Spoofed Packets, Source Routed Packets, Redirect Packets

To turn on logging for Spoofed Packets, Source Routed Packets, and Redirect Packets, edit the /etc/sysctl.conf file and add the following line:

net.ipv4.conf.all.log_martians = 1
Note
Note

Because of the way SUSE Linux Enterprise Server is set up (with rsyslog) for network event tracking, keep in mind that this can cause a large amount of messages to be logged.

3.9.9 Buffer Overflow Attack Mitigation

Starting with the 2.6.x kernel releases, Linux offers Address Space Layout Randomization (ASLR) and the No-eXecute (NX bit) for mitigation of buffer overflow attacks. For more information, see:

Since version 12, SUSE Linux Enterprise Server already comes with some buffer overflow attack mitigation techniques being enabled by default.

ASLR is enabled by default. This can be verified with the output of the following command. The expected result is 2:

tux > cat /proc/sys/kernel/randomize_va_space
2

This randomizes the heap, stack, and load addresses of dynamically linked libraries. Programs that run privileged or process network data are already built using special compiler flags (PIE and _FORTIFY_SOURCE) to take even more advantage of randomizing the text and data segments as well.

Executable space protection prevents the execution of memory space that is not intended for execution. Linux makes use of the No eXecute bit. This is enabled by default on the SUSE Linux Enterprise Server kernel for the x86 and AMD64/Intel 64 architecture. Use of the NX bit has to be supported by each individual program. You can check if your system supports the NX bit:

tux > dmesg | grep '[NX|DX]*protection'
[    0.000000] NX (Execute Disable) protection: active

If NX is disabled, check your BIOS or UEFI for a setting that enables it and make sure that it is supported by your CPU.

Furthermore, since version 12, SUSE Linux Enterprise Server prevents leaking of internal kernel addresses to make kernel exploits harder by setting the kptr_restrict:

tux > cat /proc/sys/kernel/kptr_restrict
1

On CPU's that support it (newer AMD64/Intel 64 CPUs) the kernel also uses the SMEP protection by default that prevents direct execution of user space code from inside the kernel. This is often used by kernel exploits and therefore a good hardening measure.

3.9.10 File system hardening

To mitigate vulnerabilities based on insecure file system access by privileged programs (tmp-races, TOCTOU) the Linux kernel offers two sysctl variables which should already be enabled by default on SUSE Linux Enterprise Server 12 SP3: fs.protected_hardlinks and fs.protected_symlinks or their corresponding /proc entries:

tux > cat /proc/sys/fs/protected_hardlinks
1

By setting this to 1, users can no longer create soft or hard links to files which they do not own. This mitigates a commonly used exploitation vector for programs which call open(2), creat(2) or similar functions without care.

tux > cat /proc/sys/fs/protected_symlinks
1

By setting this to 1, symbolic links are permitted to be followed only when outside a sticky world-writable directory, or when the uid of the link and follower match, or when the directory owner matches the symlink's owner.

3.9.11 Increased dmesg Restrictions

dmesg provides all kinds of system internal information, such as kernel addresses, crashes of services, and similar things that could be used by local attackers. This is why the access to dmesg is restricted to root by default. The behavior is controlled by the kernel.dmesg_restrict option (defaults to 1). If set to 0, any user can view the output of dmesg.

3.9.12 Filter access to /dev/mem (default in SUSE Linux Enterprise Server 12)

/dev/mem hosts an image of the system's main memory, including kernel and user space memory. Allowing unfiltered access to this information is dangerous and therefore the kernel on SUSE Linux Enterprise Server has been compiled with CONFIG_STRICT_DEVMEM enabled. This setting restricts user space access to /dev/mem to memory mapped peripherals.

3.10 AppArmor

Included with SUSE Linux Enterprise Server, AppArmor is an application security tool designed to provide an easy-to-use security framework for your applications. AppArmor proactively protects the operating system and applications from external or internal threats, even zero-day attacks, by enforcing a specified behavior and preventing some unknown application flaws from being exploited. AppArmor security policies, called profiles, completely define which system resources and files can be accessed by each application. The profiles also define the access mode, for example read or write. Several default profiles are included with AppArmor, and using a combination of advanced static analysis and learning-based tools, AppArmor profiles for even very complex applications can be deployed successfully in a matter of hours.

AppArmor consists of:

  • A kernel extension which enforces the security profiles.

  • A collection of RPMs, also shipped with SUSE Linux Enterprise Server that provides:

    • A set of AppArmor profiles for numerous programs that ship with SUSE Linux Enterprise Server.

    • Tools to create and manage new and existing AppArmor profiles.

    • A YaST user interface to manage reports and notification of security events.

    • Documentation about the AppArmor tools.

It is best to reboot a system after completing installation, so that AppArmor can confine all system daemons.

The AppArmor quick-start and administrative guides are available online here:

http://www.suse.com/documentation/apparmor/

For additional details and step-by-step instructions on the usage and configuration of AppArmor you can also refer to Part IV, “Confining Privileges with AppArmor.

3.11 SELinux

SELinux is an advanced technology for securing Linux systems. It is included with basic enablement in SUSE Linux Enterprise Server 12 SP3, and is included with some other distributions by default. Hardening Linux using SELinux technology, on its own, warrants its own security HOWTO and is out of scope for this guide. The book SELinux: NSA's Open Source Security Enhanced Linux contains a very good description of its setup and usage. As part of the basic enablement, SELinux will not be officially supported, but packages have now been added to SUSE Linux Enterprise Server 12 SP3 to enable its usage with minimal effort. While AppArmor is much easier to use and has a similar feature set, knowing both will most certainly be beneficial.

3.12 FTP, telnet, and rlogin (rsh)

The programs/protocols of FTP, telnet, and rlogin (rsh) are vulnerable to eavesdropping, which is one of the main reasons secure alternatives such as ssh, scp or sftp should be used instead. It is highly recommended not to run the insecure services. Because of the high risk, this guide does not cover these services (other than vsftp). It would also be a good idea (and part of our guidance, see next section) not to have FTP and Telnet server RPMs installed on the system. Note that the EAL 4+ evaluation had vsftp installed. The vs stands for very secure—which is a differentiator here when compared to normal FTP.

3.13 Removing Unnecessary Software Packages (RPMs)

A very important step in securing a Linux system is to determine the primary function(s) or role(s) of the Linux server. Otherwise, it can be difficult to understand what needs to be secured and securing these Linux systems can prove ineffective. Therefore, it is critical to look at the default list of software packages and remove any unnecessary packages or packages that do not comply with your defined security policies.

Doing this will result in fewer packages that require updates and will simplify maintenance efforts when security alerts and patches are released. It is a best practice not to install, among others, development packages or desktop software packages (for example, an X Server) on production servers. If you do not need them, you should also uninstall, for example, the Apache Web server or Samba file sharing server.

Important
Important: Requirements of Third-party Installers

Many third-party vendors like Oracle and IBM require a desktop environment and development libraries to run installers. To avoid this from having an impact on the security of their production servers, many organizations work around this by creating a silent installation (response file) in a development lab.

Also, other packages like FTP and Telnet daemons should not be installed as well unless there is a justified business reason for it (again, ssh, scp or sftp should be used as replacements).

One of the first action items should be to create a Linux image that only contains RPMs needed by the system and applications, and those needed for maintenance and troubleshooting purposes. A good approach is to start with a minimum list of RPMs and then add packages as needed. This process is time-consuming but usually worth the effort.

Tip
Tip: Just Enough Operating System (JeOS)

The SUSE Appliance Program includes a component called JeOS (Just Enough Operating System). JeOS has a very small footprint and can be customized to fit the specific needs of a system developer. Main uses of JeOS are for hardware/software appliance or virtual machine development. Key benefits of JeOS are efficiency, higher performance, increased security and simplified management.

If JeOS is not an option for you, a good choice is the minimal installation pattern.

To generate a list of all installed RPMs, use the following command:

root # rpm -qa

To retrieve details about a particular RPM (from the RPM itself), run:

root # rpm -qi PACKAGE_NAME

To check for and report potential conflicts and dependencies when deleting an RPM, run:

root # rpm -e --test PACKAGE_NAME

This can be very useful, as running the removal command without a test can often yield a mass of complaints and require manual recursive dependency hunting.

3.14 Patching Linux Systems

Building an infrastructure for patch management is another very important part of a proactive and secure production Linux environment.

It is recommended to have a written security policy and procedure to handle Linux security updates and issues. For example, a security policy should detail the time frame for assessment, testing, and roll out of patches. Network related security vulnerabilities should get the highest priority and should be addressed immediately within a short time frame. The assessment phase should occur within a testing lab, and initial roll out should occur on development systems first

A separate security log file should contain details on which Linux security announcements have been received, which patches have been researched and assessed, when patches have been applied, etc.

SUSE releases their patches in three categories, security, recommended and optional. There are a few options that can be used to keep systems patched, up to date and secure. Each system can register and then retrieve updates via the SUSE Update Web site using the included YaST tool—YaST Online Update. SUSE has also created the Subscription Management Tool (SMT), an efficient way to maintain a local repository of available/released patches/updates/fixes that systems can then pull from (reducing Internet traffic). SUSE also offers SUSE Manager for the maintenance, patching, reporting and centralized management of Linux systems, not only SUSE, but other distributions as well.

3.14.1 YaST Online Update

On a per-server basis, installation of important updates and improvements is possible using the YaST Online Update tool. Current updates for the SUSE Linux Enterprise family are available from the product specific update catalogs containing patches. Installation of updates and improvements is accomplished using YaST and selecting Online Update in the Software Group. All new patches (except the optional ones) that are currently available for your system will already be marked for installation. Clicking Accept will then automatically install these patches.

3.14.2 Automatic Online Update

YaST also offers the possibility to set up an automatic update. Select Software ›  Automatic Online Update. Configure a Daily or a Weekly update. Some patches, such as kernel updates, require user interaction, which would cause the automatic update procedure to stop. Check Skip Interactive Patches for the update procedure to proceed automatically.

In this case, run a manual Online Update from time to install patches that require interaction.

When Only Download Patches is checked, the patches are downloaded at the specified time but not installed. They must be installed manually using rpmor zypper.

3.14.3 Subscription Management Tool—SMT

The Subscription Management Tool for SUSE Linux Enterprise goes one step further than the Online Update process by establishing a proxy system with repository and registration targets. This helps customers centrally manage software updates within the firewall on a per-system basis, while maintaining their corporate security policies and regulatory compliance.

The downloadable SMT (http://download.suse.com/) is integrated with SUSE Customer Center (https://scc.suse.com/) and provides a repository and registration target that is synchronized with it. This can be very helpful in tracking entitlements in large deployments. The SMT maintains all the capabilities of SUSE Customer Center, while allowing a more secure centralized deployment. It is included with every SUSE Linux Enterprise subscription and is therefore fully supported.

The SMT provides an alternative to the default configuration, which requires opening the firewall to outbound connections for each device to receive updates. That requirement often violates corporate security policies and can be seen as a threat to regulatory compliance by some organizations. Through its integration with SUSE Customer Center, the SMT ensures that each device can receive its appropriate updates without the need to open the firewall, and without any redundant bandwidth requirements.

The SMT also enables customers to locally track their SUSE Linux Enterprise devices (that is servers, desktops, or Point of Service terminals) throughout their enterprise. Now they can easily determine how many entitlements are in need of renewal at the end of a billing cycle without having to physically walk through the data center to manually update spreadsheets.

The SMT informs the SUSE Linux Enterprise devices of any available software updates. Each device then obtains the required software updates from the SMT. The introduction of the SMT improves the interaction among SUSE Linux Enterprise devices within the network and simplifies how they receive their system updates. The SMT enables an infrastructure for several hundred SUSE Linux Enterprise devices per instance of each installation (depending on the specific usage profile). This offers more accurate and efficient server tracking.

In a nutshell, the Subscription Management Tool for SUSE Linux Enterprise provides customers with:

  • Assurance of firewall and regulatory compliance

  • Reduced bandwidth usage during software updates

  • Full support under active subscription from SUSE

  • Maintenance of existing customer interface with SUSE Customer Center

  • Accurate server entitlement tracking and effective measurement of subscription usage

  • Automated process to easily tally entitlement totals (no more spreadsheets!)

  • Simple installation process that automatically synchronizes server entitlement with SUSE Customer Center

3.14.4 SUSE Manager

SUSE Manager automates Linux server management, allowing you to provision and maintain your servers faster and more accurately. It monitors the health of each Linux server from a single console so you can identify server performance issues before they impact your business. And it lets you comprehensively manage your Linux servers across physical, virtual and cloud environments while improving data center efficiency. SUSE Manager delivers complete life cycle management for Linux:

  • Asset management

  • Provisioning

  • Package management

  • Patch management

  • Configuration management

  • Redeployment

For more information on SUSE Manager refer to https://www.suse.com/products/suse-manager/.

3.15 Securing the Network—Open Network Ports Detection

Securing a server requires that you know what it is serving; what services are running. Default server installations may have services running that aren't self apparent and open network ports that they are using. So, one of the most important tasks is to detect and close network ports that are not needed. To get a list of listening network ports (TCP and UDP sockets), you can use the netstat service run the following command:

root # netstat -tulp

Be aware that netstat output can be wider than a default terminal screen. If the screen is too narrow, the options described above will likely cause the output to wrap and be less legible.

Below is an example of output from the above command:

Proto Recv-Q Send-Q Local            Foreign         State   PID/Program
                    Address          Address                 name
tcp   0      0      *:auth           *.*             LISTEN  2328/xinetd
tcp   0      0      local[...].:smtp *.*             LISTEN  2360/sendmail:acce
tcp   0      0      *:ssh            *.*             LISTEN  2317/sshd

From the output above you can see that three TCP-based services are running and listening: xinetd, sendmail, and sshd. Sendmail should not be configured to listen for incoming network connections unless the server running it is a designated as a mail or relay server. Running a port scan from another server can confirm that, but make sure to obtain proper permissions to scan/probe a machine on a production network.

Important
Important

Some organizations consider port scans without permission a security offense.

Using the Nmap tool, such a probe/scan can be run:

root # nmap -sTU REMOTE_HOST
Starting nmap 3.70 ( http://www.insecure.org/nmap/ ) at 2004-12-10 22:51 CST
Interesting ports on venus (192.168.2.101):
(The 3131 ports scanned but not shown below are in state: closed)
PORT     STATE         SERVICE
22/tcp   open          ssh
113/tcp  open          auth

Nmap run completed -- 1 IP address (1 host up) scanned in 221.669 seconds

Note that running the nmap command can take quite a while (in this example almost 4 minutes) depending on the options used. If you remove the UDP port scan (leave out the -U option), then nmap will finish the port scan nearly immediately. The results of nmap can vary widely and might not show all listening network sockets depending on the status of the SuSEFirewall2 (or other) and if it has been set up to block any ports.

From the sample run above, you see that the xinetd daemon is listening on port auth (port 113) for IDENT (for more information on this service, see Section 3.16, “xinetd Services - Disabling”). You can also see that sendmail is not listening for remote incoming network connections.

Another method to list all of the TCP and UDP sockets to which programs are listening (on a host) is to use the lsof command – which lists open files:

root # lsof -i -n | egrep 'COMMAND|LISTEN|UDP'
COMMAND  PID   USER   FD   TYPE    DEVICE SIZE/OFF NODE NAME
sshd     2317  root   3u   IPv6    6579   0t0      TCP *:ssh (LISTEN)
xinetd   2328  root   5u   IPv4    6698   0t0      TCP *:auth (LISTEN)
sendmail 2360  root   3u   IPv4    6729   0t0      TCP 127.0.0.1:smtp (LISTEN)

3.16 xinetd Services - Disabling

The xinetd daemon is a replacement for inetd, the Internet services daemon. It monitors the ports for all network services configured in /etc/xinetd.d, and starts the services in response to incoming connections. To check if xinetd is enabled and running, execute:

root # systemctl status xinetd

To check the current status of the xinetd service, execute:

root # systemctl status xinetd

If xinetd is active, it is very important to see which services are active and being controlled by xinetd. The following command will list all services configured in /etc/xinetd.d and whether xinetd monitors the ports for these services:

root # chkconfig -list | awk '/xinetd based services/,/""/'
xinetd based services:

  chargen:     off
  chargen-udp: off
  cups-lpd:    off
  cvs:         off
  daytime:     off
  daytime-udp: off
  discard:     off
  discard-udp: off
  echo:        off
  echo-udp:    off
  netstat:     off
  rsync:       off
  sane-port:   off
  servers:     off
  services:    off
  svnserve:    off
  swat:        off
  systat:      off
  tftp:        on
  time:        off
  time-udp:    off
  vnc:         off

To get a list of only active services for which xinetd monitors the ports, you could run (where the -v option of grep does an inverse-match) :

root # chkconfig --list | awk '/xinetd based services/,/""/' | grep -v off
xinetd based services:

  tftp:        on

In the above example you can see that the telnet-server package is not installed on the system. If the Telnet Server package telnet-server would be installed, it would show up on the list whether it is active. Here is an example how to disable a service. Assuming the tftp service is active, run the following commands to disable it and to see how the telnet service entries are being updated:

tux > sudo systemctl status tftp
tftp.service - Tftp Server
Loaded: loaded (/usr/lib/systemd/system/tftp.service; static)
Active: active (running) since Fri 2014-09-05 07:56:23 CEST; 2h 1min ago

# sudo cat /etc/xinetd.d/tftp | grep disable
   disable = no

# sudo systemctl disable tftp

# systemctl status tftp
tftp.service - Tftp Server
Loaded: loaded (/usr/lib/systemd/system/tftp.service; static)
Active: inactive (dead)

# sudo cat /etc/xinetd.d/tftp | grep disable
      disable = yes

For the TFTP service it would be better to remove the package from the system since removal is always safer than disabling (when possible):

root # rpm -e tftp

3.16.1 Inventory xinetd services

It is important to investigate all active xinetd services and to disable them (or remove their packages) if they are not needed. To find out what a service does, here is a viable approach. Using the tftp service as an example and assuming its function is unknown and it is listed as an active service. Execute the following commands:

root # grep " server" /etc/xinetd.d/tftp
  server = /usr/sbin/in.tftpd
  server_args = -s /tftpboot

To read the manual:

root # man in.tftpd
TFTPD(8)               System Manager's Manual              TFTPD(8)



NAME
       tftpd - IPv4 Trivial File Transfer Protocol server

SYNOPSIS
       in.tftpd [options...]  directory...

DESCRIPTION
       tftpd  is  a  server  for the Trivial File Transfer Protocol.
       The TFTP protocol is extensively used to support remote boot-
       ing  of  diskless devices.  The server is normally started by
       inetd, but can also run stand-alone.
[...]

To determine what package supplies the in.tftpd binary:

root # rpm -qf /usr/sbin/in.tftpd
tftp-0.48-101.16

To get a description of TFTP and its usage, etc:

root # rpm -qi tftp-0.48-101.16| awk '/Description/,/""/'
Description :
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations and for getting or saving network
component configuration files.

To get a list of what files are installed via the TFTP package (RPM), execute the rpm command with the following options:

root # rpm -ql tftp-0.48-101.16
/etc/xinetd.d/tftp
/usr/bin/tftp
/usr/sbin/in.tftpd
/usr/share/doc/packages/tftp
/usr/share/doc/packages/tftp/README
/usr/share/doc/packages/tftp/README.security
/usr/share/doc/packages/tftp/sample.rules
/usr/share/man/man1/tftp.1.gz
/usr/share/man/man8/in.tftpd.8.gz
/usr/share/man/man8/tftpd.8.gz

This example described what could be done to find out information about services (specifically ones started by xinetd) even if an online manual did not exist for the binary in.ftpd. This example yielded a man page – but you may not always find one. The RPM commands in the example are very commonly used for a variety of reasons. It is also possible to use the YaST software management interface to retrieve all of the resultant information – however having a knowledge of RPM command syntax can save quite a bit of time. Again to disable the TFTP service, execute the following command:

root # systemctl disable tftp

The xinetd daemon is quite flexible and has many features. Here are a few functionalities of xinetd:

  • Access control for TCP, UDP, and RPC services.

  • Access limitations based on time.

  • Provides mechanisms to prevent DoS attacks.

For more specific information on Xinetd, review the documentation and usage examples at the xinetd GitHub page https://github.com/xinetd-org/xinetd.

3.17 Securing Postfix

Postfix is a replacement for Sendmail and has several security advantages over Sendmail. Postfix is the default mail system in SUSE Linux Enterprise Server and consists of several small programs that each perform their own small task—most of these programs run in a chroot jail. This is one of the reasons Postfix is recommended over Sendmail.

Linux servers that are not dedicated mail or relay servers should not accept external e-mails. However, it is important for production servers to send local e-mails to a relay server—some security setups (for example the seccheck scripts) can be configured to send e-mails to someone other than root, even off the local system.

Verify the following parameters in /etc/postfix/main.cf are set to ensure that Postfix accepts only local e-mails for delivery (look toward the bottom of the file as the top portion is mostly commented-out example entries and explanations):

mydestination = $myhostname, localhost.$mydomain, localhost
inet_interfaces = localhost

The mydestination parameter lists all domains to receive e-mails for. The inet_interfaces parameter specifies the network to listen on. After reconfiguring Postfix, a restart of the mail system is necessary:

root # systemctl restart postfix

Verify that Postfix is not listening for network requests (incoming) by running one of these commands from another host:

nmap -sT -p 25 REMOTE_HOST
telnet <remote_host> 25
Note
Note

Running these commands on the local host will provide inaccurate results because Postfix is supposed to accept connections from the local node. Use an external host for correct results.

3.18 File Systems: Securing NFS

NFS (Network File System) allows servers to share files over a network. But like all network services using NFS involves risks.

Here are some basic rules:

  • NFS should not be enabled if not needed.

  • If NFS is truly needed, use a TCP wrapper to restrict remote access.

  • Ensure to export only to those hosts that really need access.

  • Use a fully qualified domain name to diminish any spoofing attempts.

  • Export only as read-only whenever possible.

  • Use NFS only over TCP.

If you do not have shared directories to export, then ensure that the NFS service is not enabled nor running on the system:

Check the NFS service status:

root # systemctl status nfsserver

Check the current targets:

root # ls /etc/systemd/system/*.wants/nfsserver.service

3.18.1 Enabling and Starting NFS Server

If NFS must be used, it can be activated using the following commands on SUSE Linux Enterprise Server or more simply and securely with the YaST plug-in (ncurses). Access it directly from command line with yast nfs_server or yast nfs_client – or manually:

root # systemctl enable nfs
systemctl start nfs

Portmapper information:

root # rpcinfo -p SERVERNAME
   program vers proto   port
    100000    2   tcp    111  portmapper
    100000    2   udp    111  portmapper
    100003    2   udp   2049  nfs
    100003    3   udp   2049  nfs
    100003    2   tcp   2049  nfs
    100003    3   tcp   2049  nfs
    100005    1   udp    623  mountd
    100005    1   tcp    626  mountd
    100005    2   udp    623  mountd
    100005    2   tcp    626  mountd
    100005    3   udp    623  mountd
    100005    3   tcp    626  mountd

If you run it from an "untrusted" server or network, you should get the following output:

root # rpcinfo -p SERVERNAME
No remote programs registered.

3.18.2 Exporting NFS

To allow a client access to a file system or directory, the /etc/exports file serves as the access control list. To give the network "network.example.com" read-only access to /pub, the entries in /etc/exports would look like as follows:

      /pub *.network.example.com(ro,sync)

It is very important not to give write access to NFS clients if not absolutely needed! Entries in /etc/exports are exported read-only (ro option) by default. To allow servers sles-ha1, sles-ha2 and sles-ha3 read-write access to the /data/MYSQL directory, the entries in /etc/exports would look like as follows:

/data/MYSQL sles-ha1.example.com(rw,sync) sles-ha2.example.com(rw,sync) sles-ha3.example.com(rw,sync)

Note that the options must not be separated from the host names or networks with whitespace(s). Also, fully qualified domain names should always be used to diminish spoofing attempts. All entries in /etc/exports are exported with the root_squash option (root squashing) by default. This means that a root user on a client machine does not have root privileges (root access) to files on exported NFS. It is not recommended to turn root squashing off using the no_root_squash option! After you have made all your entries in /etc/exports, you can export all file systems/directories using the following command:

root # exportfs -a

To unexport all shared file systems/directories, run:

root # exportfs -ua

To see all shared file systems/directories, run:

root # showmount -e localhost
Export list for localhost:

/pub *.network.example.com/data/MYSQL
sles-ha1.example.com,sles-ha2.example.com,sles-ha3.example.com

3.18.3 Using NFS over TCP

If you need NFS, it is recommended to use NFS only over TCP since NFS over UDP is not secure. All 2.4 and later kernels support NFS over TCP on the client side. Server support for TCP appeared in later 2.4 kernels and beyond. To mount a shared directory using NFS over TCP, it is necessary to use the proto=tcp mount option:

root # mount -o proto=tcp SERVERNAME:/pub /usr/local/pub

Verify that the target directory, in this case /usr/local/pub, exists on the client:

root # mount [...] SERVERNAME:/pub on
/usr/local/pub type nfs (rw,proto=tcp,addr=192.168.1.110)

To have the shared directory mounted on the client at boot time, use the /etc/fstab file. For the above example, the /etc/fstab entry could look like this:

SERVERNAME:/pub /usr/local/pub nfs rsize=8192,wsize=8192,timeo=14,intr,tcp 0 0

3.19 Copying Files Using SSH Without Providing Login Prompts

This example is needed in some cases to enable files to be copied over the network using SSH without providing an interactive login prompt. This allows trusted hosts to be set up—an example of federation.

SSH can allow a forced command using the command option. Using this option it is possible to disable scp (secure copy) and enforce every passed ssh command to be ignored. On the server side where you want to retrieve the file from, add the following entry to the beginning of the SSH key in the ~/.ssh/authorized_keys file (the ~ represents a particular users home directory – root's home directory is /root – other users typically reside in /home/USERNAME):

command="/bin/cat ~/<file_name>" ssh-rsa AAAAB3N...{etc}

To copy now the file from the remote server, run the following command:

ssh USER@SERVERNAME LOCAL_FILE

Since /bin/cat is run on the server side, its output needs to be redirected to the local file.

Another approach is to replace the /bin/cat (referenced above) with your own script that checks the passed SSH commands by reading the environment variable $SSH_ORIGINAL_COMMAND. For example:

#!/bin/ksh
 if [[ $SSH_ORIGINAL_COMMAND = "File1" ||
       $SSH_ORIGINAL_COMMAND = "File2" ]]
 then
     /bin/cat $SSH_ORIGINAL_COMMAND
 else
     echo "Invalid file name!"
     exit 1
 fi

So you replace the /bin/cat portion with the script name in ~/.ssh/authorized_keys, and run the following command to copy Foo1:

tux > ssh USER@SERVERNAME Foo1 > LOCAL_FILE

To copy Foo 2, run:

tux > ssh USER@SERVERNAME Foo2 > LOCAL_FILE

With the modifications above, every other variety of passed parameters will return errors.

3.20 Checking File Permissions and Ownership

The following sections deal with some ways the default permissions and file settings can be modified to enhance the security of a host. It is important to note that the use of the default SUSE Linux Enterprise Server utilities like seccheck - can be run to lock down and improve the general file security and user environment. However, it is beneficial to understand how to modify these things.

SUSE Linux Enterprise Server hosts include 3 defaults settings for file permissions: permissions.easy, permissions.secure, and permissions.paranoid, all located in the /etc directory. The purpose of these files is to define special permissions, such as world-writable directories or, for files, the setuser ID bit (programs with the setuser ID bit set do not run with the permissions of the user that has launched it, but with the permissions of the file owner, usually root).

Administrators can use the file /etc/permissions.local to add their own settings. The easiest way to implement one of the default permission rule-sets above is to use the Local Security module in YaST.

Each of the following topics will be modified by a selected rule-set, but the information is important to understand on its own.

3.21 Default umask

The umask (user file-creation mode mask) command is a shell built-in command which determines the default file permissions for newly created files. This can be overwritten by system calls but many programs and utilities use umask. By default, SUSE sets umask to 022. You can modify this by changing the value in /etc/profile.

The id command will print out the current user identity information. Example from a non-root prompt:

tux > id
uid=1000(ne0) gid=100(users) groups=16(dialout),33(video),100(users)

And to determine the active umask, use the umask command:

tux > umask
0022

Now, for comparison's sake, the same commands from the root user:

root # id
uid=0(root) gid=0(root) groups=0(root)
root # umask
0022

3.22 SUID/SGID Files

When the SUID (set user ID) or SGID (set group ID) bits are set on an executable, it executes with the UID or GID of the owner of the executable rather than that of the person executing it. This means that, for example, all executables that have the SUID bit set and are owned by root are executed with the UID of root. A good example is the passwd command that allows ordinary users to update the password field in the /etc/shadow file which is owned by root.

But SUID/SGID bits can be misused when the SUID/SGID executable has a security hole. Therefore, you should search the entire system for SUID/SGID executables and document it. For example, ensure that code developers do not set SUID/SGID bits on their programs if it is not an absolute requirement. Very often you can use workarounds like removing the executable bit for world/others. However, a better approach is to change the design of the software if possible.

To search the entire system for SUID or SGID files, you can run the following command:

root # find / -path /proc -prune -o -type f -perm '/6000' -ls

The -prune option in this example is used to skip the /proc file system.

3.23 World-Writable Files

World-writable files are a security risk since it allows anyone to modify them. Additionally, world-writable directories allow anyone to add or delete files. To locate world-writable files and directories, you can use the following command:

root # find / -path /proc -prune -o -perm -2 ! -type l -ls

The ! -type l parameter skips all symbolic links since symbolic links are always world-writable. However, this is not a problem as long as the target of the link is not world-writable, which is checked by the above find command.

World-writable directories with sticky bit—directory or file ownership where only the item's owner, the directory's owner, or root can rename or delete files—such as the /tmp directory do not allow anyone except the owner of a file to delete or modify it in this directory. The sticky bit makes files stick to the user who created it and it prevents other users from deleting and renaming the files. Therefore, depending on the purpose of the directory world-writable directories with sticky are usually not an issue. An example is the /tmp directory:

tux > ls -ld /tmp
drwxrwxrwt 18 root root 16384 Dec 23 22:20 /tmp

The t mode, which denotes the sticky bit, allows files to be deleted and renamed only if the user is the owner of this file or the owner of the directory.

SUSE Linux Enterprise Server supports file capabilities to allow more fine grained privileges to be given to programs rather than the full power of root:

root # getcap -v /usr/bin/ping
      /usr/bin/ping = cap_new_raw+eip

The previous command only grants the CAP_NET_RAW capability to whoever executes ping. In case of vulnerabilities inside ping, an attacker can gain at most this capability in contrast to full root when granting the ping binary suid root rights. Whenever possible, file capabilities should be chosen in favor of the suid-to-root bit. But this only applies when the binary is suid to root, not to other users such as news, lp and alike.

3.24 Orphaned or Unowned Files

Files not owned by any user or group might not necessarily be a security problem in itself. However, unowned files could pose a security problem in the future. For example, if a new user is created and the new users happens to get the same UID as the unowned files have, then this new user will automatically become the owner of these files.

To locate files not owned by any user or group, use the following command:

root # find / -path /proc -prune -o -nouser -o -nogroup

3.25 Restricting Access to Removable Media

In some environments it is required to restrict access to removable media such as USB storage or optical devices. The tools coming with the udisks2 package help with such a configuration.

  1. Create a rules file /etc/polkit-1/rules.d/01-restrict-removable-media.rules similar to the following:

    // Allow users in group 'mmedia_all' to mount/unmount all type of drives
    // Allow users in group 'mmedia_removable' to mount/umount USB storage drives
    // Allow users in group 'mmedia_optical' to mount/unmount Optical drives
    polkit.addRule(function(action, subject) {
      if (/^org\.freedesktop\.udisks2\.filesystem-.*mount.*$/.test(action.id) &&
      action.lookup("drive.removable") == "true") {
        if (subject.isInGroup("mmedia_all")) {
          return polkit.Result.YES;
        } else {
          if (/.*optical.*/.test(action.lookup("drive.removable.media"))) {
            if (subject.isInGroup("mmedia_optical"))
            return polkit.Result.YES;
          } else if (/.*floppy.*/.test(action.lookup("drive.removable.media"))) {
            return polkit.Result.NO;
          } else if (action.lookup("drive.removable.bus") == "usb") {
            if (subject.isInGroup("mmedia_removable"))
            return polkit.Result.YES;
          }
          return polkit.Result.NO;
        }
      }
    });
    Important
    Important: Naming of the Rules File

    Rules files are processed in alphabetical order. Functions are called in the order they were added until one of the functions returns a value. Hence, to add an authorization rule that is processed before other rules, put it in a file in /etc/polkit-1/rules.d with a name that sorts before other rules files, for example 01-restrict-removable-media.rules. Each function should return a value from polkit.Result.

    The name of a rules file must start with a digit, otherwise it will be ignored.

  2. Restart udisks2:

    root # systemctl restart udisks2
  3. Restart polkit

    root # systemctl restart polkit
  4. In YaST, click Security and Users › User and Group Management › Groups to create the three groups mmedia_all, mmedia_optical, and mmedia_removable. Then add the users to these groups as wanted.

3.26 Various Account Checks

3.26.1 Unlocked Accounts

It is important that all system and vendor accounts that are not used for logins are locked. To get a list of unlocked accounts on your system, you can check for accounts that do not have an encrypted password string starting with ! or * in the /etc/shadow file. If you lock an account using passwd -l, it will put a !! in front of the encrypted password, effectively disabling the password. If you lock an account using usermod -L, it will put a ! in front of the encrypted password. Many system and shared accounts are usually locked by default by having a * or !! in the password field which renders the encrypted password into an invalid string. Hence, to get a list of all unlocked (encryptable) accounts, run (egrep is used to allow use of regular-expressions):

root # egrep -v ':\*|:\!' /etc/shadow | awk -F: '{print $1}'

Also make sure all accounts have a x in the password field in /etc/passwd. The following command lists all accounts that do not have a x in the password field:

root # grep -v ':x:' /etc/passwd

An x in the password fields means that the password has been shadowed, for example the encrypted password needs to be looked up in the /etc/shadow file. If the password field in /etc/passwd is empty, then the system will not look up the shadow file and it will not prompt the user for a password at the login prompt.

3.26.2 Unused Accounts

All system or vendor accounts that are not being used by users, applications, by the system or by daemons should be removed from the system. You can use the following command to find out if there are any files owned by a specific account:

root # find / -path /proc -prune -o -user ACCOUNT -ls

The -prune option in this example is used to skip the /proc file system. If you are sure that an account can be deleted, you can remove the account using the following command:

root # userdel -r ACCOUNT

Without the -r option userdel will not delete the user's home directory and mail spool (/var/spool/mail/USER). Note that many system accounts have no home directory.

3.27 Enabling Password Aging

Password expirations are a general best practice—but might need to be excluded for some system and shared accounts (for example Oracle, etc.). Expiring password on those accounts could lead to system outages if the application account expires.

Typically a corporate policy should be developed that dictates rules/procedures regarding password changes for system and shared accounts. However, normal user account passwords should expire automatically. The following example shows how password expiration can be set up for individual user accounts.

The following files and parameters in the table can be used when a new account is created with the useradd command. Settings such as these are stored for each user account in the /etc/shadow file. If using the YaST tool (User and Group Management) to add users, the settings are available on a per-user basis. Here are the various settings—some of which can also be system-wide (for example modification of /etc/login.defs and /etc/default/useradd):

/etc/login.defs

PASS_MAX_DAYS

Maximum number of days a password is valid.

/etc/login.defs

PASS_MIN_DAYS

Minimum number of days before a user can change the password since the last change.

/etc/login.defs

PASS_WARN_AGE

Number of days when the password change reminder starts.

/etc/default/useradd

INACTIVE

Number of days after password expiration that account is disabled.

/etc/default/useradd

EXPIRE

Account expiration date in the format YYYY-MM-DD.

Note
Note

Users created prior to these modifications will not be affected.

Ensure that the above parameters are changed in the /etc/login.defs and /etc/default/useradd files. Review of the /etc/shadow file will show how these settings get stored after adding a user.

To create a new user account, execute the following command:

root # useradd -c "TEST_USER" -g USERS TEST

The -g option specifies the primary group for this account:

root # id TEST
uid=509(test) gid=100(users) groups=100(users)

The settings in /etc/login.defs and /etc/default/useradd are recorded for the test user in the /etc/shadow file as follows:

root # grep TEST /etc/shadow
test:!!:12742:7:60:7:14::

Password aging can be modified at any time by use of the chage command. To disable password aging for system and shared accounts, you can run the following chage command:

root # chage -M -1 SYSTEM_ACCOUNT_NAME

To get password expiration information:

root # chage -l SYSTEM_ACCOUNT_NAME

For example:

root # chage -l TEST
Minimum: 7
Maximum: 60
Warning: 7
Inactive: 14
Last Change: Jan 11, 2015
Password Expires: Mar 12, 2015
Password Inactive: Mar 26, 2015
Account Expires: Never

3.28 Stronger Password Enforcement

On an audited system it is important to restrict people from using simple passwords that can be cracked too easily. Writing down complex passwords is all right as long as they are stored securely. Some will argue that strong passwords protect you against dictionary attacks and those type of attacks can be defeated by locking accounts after a few failed attempts. However, this is not always an option. If set up like this, locking system accounts could bring down your applications and systems which would be nothing short of a denial of service attack – another issue.

At any rate, it is important to practice effective password management safety. Most companies require that passwords have at the very least a number, one lowercase letter, and one uppercase letter. Policies vary, but maintaining a balance between password strength/complexity and management is sometimes difficult.

3.29 Leveraging an Effective PAM stack

  • Filename: hardening_pam_stack.xml
  • ID: sec.sec_prot.general.pam

Linux-PAM (Pluggable Authentication Modules for Linux) is a suite of shared libraries that enable the local system administrator to choose how applications authenticate users.

It is strongly recommended to familiarize oneself with the capabilities of PAM and how this architecture can be leveraged to provide the best authentication setup for an environment. This configuration can be done once – and implemented across all systems (a standard) or can be enhanced for individual hosts (enhanced security – by host / service / application). The key is to realize how flexible the architecture is.

To learn more about the PAM architecture, find PAM documentation in the /usr/share/doc/packages/pam directory (in a variety of formats).

The following discussions are examples of how to modify the default PAM stacks—specifically around password policies—for example password strength, password re-use and account locking. While these are only a few of the possibilities, they serve as a good start and demonstrate PAM's flexibility.

3.29.1 Password Strength

SUSE Linux Enterprise Server can leverage the pam_cracklib library to test for weak passwords – and to suggest using a stronger one if it determines obvious weakness. The following parameters represent an example that could be part of a corporate password policy or something required because of audit constraints.

The PAM libraries follow a defined flow. The best way to design the perfect stack usually is to consider all of the requirements and policies and draw out a flow chart.

Table 3.1: Sample rules/constraints for password enforcement

pam_cracklib.so

minlen=8

Minimum length of password is 8

pam_cracklib.so

lcredit=-1

Minimum number of lowercase letters is 1

pam_cracklib.so

ucredit=-1

Minimum number of uppercase letters is 1

pam_cracklib.so

dcredit=-1

Minimum number of digits is 1

pam_cracklib.so

ocredit=-1

Minimum number of other characters is 1

To set up these password restrictions, use the pam-config tool and specify the parameters you want to configure. For example, the minimum length parameter could be modified like this:

sudo pam-config -a --cracklib-minlen=8 --cracklib-retry=3 \
--cracklib-lcredit=-1 --cracklib-ucredit=-1 --cracklib-dcredit=-1 \
--cracklib-ocredit=-1 --cracklib

Now verify that the new password restrictions work for new passwords. Simply login to a non-root account and change the password using the passwd command. Note that the above requirements are not enforced if you run the passwd command under root.

3.29.2 Restricting Use of Previous Passwords

The pam_pwhistory module can be used to configure the number of previous passwords that cannot be reused. The following command implements password restrictions on a system so that a password cannot be reused for at least 6 months:

sudo pam-config -a --pwhistory --pwhistory-remember=26

Recall that in the section Section 3.27, “Enabling Password Aging” we set PASS_MIN_DAYS to 7, which specifies the minimum number of days allowed between password changes. Therefore, if pam_unix is configured to remember 26 passwords, then the previously used passwords cannot be reused for at least 6 months (26*7 days).

The PAM configuration (/etc/pam.d/common-auth) resulting from the pam-config command looks like the following:

auth      required   pam_env.so
auth      required   pam_unix.so     try_first_pass
account   required   pam_unix.so     try_first_pass
password  requisit   pam_cracklib.so
password  required   pam_pwhistory.so        remember=26
password  optional   pam_gnome_keyring.so    use_authtok
password  required   pam_unix.so     use_authtok nullok shadow try_first_pass
session   required   pam_limits.so
session   required   pam_unix.so     try_first_pass
session   optional   pam_umask.so
Tip
Tip

Editing the PAM configuration files directly is not recommended. Use the pam-config command as shown above to fine-tune PAM. For more information see man 8 pam-config.

3.29.3 Locking User Accounts After Too Many Login Failures

It is not generally recommend that a host automatically locks system and shared accounts after too many failed login or su attempts. This could lead to outages if the application's account gets locked because of too many login failures like in this example for an Oracle shared account:

root #  su oracle -c id
su: incorrect password

This could be an easy target for a denial of service attack. The following example shows how to lock only individual user accounts after too many failed su or login attempts. Add the following line to the service files (such as /etc/pam.d/su or /etc/pam.d/login) that you want to configure (but not to /etc/pam.d/common-auth!):

auth      required     pam_tally2.so deny=5 unlock_time=1200
[...]

The line counts failed login and failed su attempts for all user accounts except the root account. The accounts will be automatically unlocked after 1200 seconds. The default location for attempted accesses is recorded in /var/log/tallylog.

If the user is authenticated and the login process continues on call to pam_setcred(3) it resets the attempts counter to 0.

It is also possible to add the lock_time=N parameter, and then optionally the unlock_time=N parameter. For example, setting the lock_time=60 would deny access for 60 seconds after a failed attempt. The unlock_time=N option would then allow access after N seconds after an account has been locked. If this option is used the user will be locked out for the specified amount of time after he exceeded his maximum allowed attempts. Otherwise the account is locked until the lock is removed by a manual intervention of the system administrator. See the pam_tally2 man page for more information.

To exempt system and shared accounts from the deny=N parameter, the per_user parameter was added to the module. The per_user parameter instructs the module not to use the deny=N limit for accounts where the maximum number of login failures is set explicitly. For example:

root #  pam_tally2 -u oracle
Login      Failures Latest failure                 From
oracle     0        Fri Dec 10 23:57:55 -0600 2005 on unknown

To instruct the module to activate the deny=N limit for this account again, run:

pam_tally2 -u oracle deny=n

By default, the maximum number of login failures for each account is set to zero (0) which instructs pam_tally2 to leverage the deny=N parameter. To see failed login attempts, run:

pam_tally2

Test these changes thoroughly on your system using ssh and su, and make sure the root id does not get locked! To lock or unlock accounts manually, run one of the following commands:

Locking
passwd -l USER
usermod -L USER
Unlocking
passwd -u USER
usermod -U USER

3.30 Preventing Accidental Denial of Service

Linux allows you to set limits on the amount of system resources that users and groups can consume. This is also very handy if bugs in programs cause them to use up too much resources (for example memory leaks), slow down the machine, or even render the system unusable. Incorrect settings can allow programs to use too many resources which may make the server unresponsive to new connections or even local logins (for example if a program uses up all available file handles on the host). This can also be a security concern if someone is allowed to consume all system resources and therefore cause a denial of service attack – either unplanned or worse, planned. Setting resource limits for users and groups may be an effective way to protect systems, depending on the environment.

3.30.1 Example for Restricting System Resources

The following example demonstrates the practical usage of setting or restricting system resource consumption for an Oracle user account. For a list of system resource settings, see /etc/security/limits.conf or man limits.conf.

Most shells like Bash provide control over various resources (for example the maximum allowable number of open file descriptors or the maximum number of processes) that are available on a per/user basis. To examine all current limits in the shell execute:

root # ulimit -a

For more information on ulimit for the Bash shell, examine the Bash man pages.

Important
Important: Setting Limits for SSH Sessions

Setting "hard" and "soft" limits might not behave as expected when using an SSH session. To see valid behavior it may be necessary to login as root and then su to the id with limits (for example, oracle in these examples). Resource limits should also work assuming the application has been started automatically during the boot process. It may be necessary to set UsePrivilegeSeparation in /etc/ssh/sshd_config to "no" and restart the SSH daemon (systemctl restart sshd) if it seems that the changes to resource limits are not working (via SSH). However this is not generally recommended – as it weakens a systems security.

Tip
Tip: Disabling Password Logins via ssh

You can add some extra security to your server by disabling password authentication for SSH. Remember that you need to have SSH keys configured, otherwise you cannot access the server. To disable password login, add the following lines to /etc/ssh/sshd_config:

UseLogin no
UsePAM no
PasswordAuthentication no
PubkeyAuthentication yes

In this example, a change to the number of file handles or open files that the user oracle can use is made by editing /etc/security/limits.conf as root making the following changes:

oracle           soft    nofile          4096
oracle           hard    nofile          63536

The soft limit in the first line defines the limit on the number of file handles (open files) that the oracle user will have after login. If the user sees error messages about running out of file handles, then the user can increase the number of file handles like in this example up to the hard limit (in this example 63536) by executing:

root # ulimit -n 63536

You can set the soft and hard limits higher if necessary.

Note
Note

It is important to be judicious with the usage of ulimits. Allowing a "hard" limit for nofile for a user that equals the kernel limit (/proc/sys/fs/file-max) is very bad! If the user consumes all the available file handles, the system cannot initiate new logins as accessing (opening) PAM modules which are required for performing a login will not be possible.

You also need to ensure that pam_limits is either configured globally in /etc/pam.d/common-auth, or for individual services like SSH, su, login, and telnet in:

/etc/pam.d/sshd (for SSH)
/etc/pam.d/su (for su)
/etc/pam.d/login (local logins and telnet)

If you do not want to enable it for all logins, there is a specific PAM module that will read the /etc/security/limits.conf file. Entries in pam configuration directives will have entries like:

session     required      /lib/security/pam_limits.so
session     required      /lib/security/pam_unix.so

It is important to note that changes are not immediate and require a new login session:

root # su – oracle
tux > ulimit -n
4096

Note that these examples are specific to the Bash shell - ulimit options are different for other shells. The default limit for the user oracle is 4096. To increase the number of file handles the user oracle can use to 63536, do:

root # su – oracle
tux > ulimit -n
4096
tux > ulimit -n 63536
tux > ulimit -n
63536

Making this permanent requires the addition of the setting, ulimit -n 63536, (again, for Bash) to the users profile (~/.bashrc or ~/.profile file) which is the user start-up file for the Bash shell on SUSE Linux Enterprise Server (to verify your shell run: echo $SHELL). To do this you could simply type (or copy/paste – if you are reading this on the system) the following commands for the Bash shell of the user oracle:

root # su - oracle
tux > cat >> ~oracle/.bash_profile << EOF
ulimit -n 63536
EOF

3.31 Displaying Login Banners

It is often necessary to place a banner on login screens on all servers for legal/audit policy reasons and to deter intruders, etc.

If you want to print a legal banner after a user logs in using SSH, local console, etc., you can leverage the /etc/motd (motd = message of the day) file. The file exists on SUSE, however it is empty. Simply add content to the file that is applicable/required by the organization.

Note
Note: Banner Length

Try to keep the content to a single page (or less), as it will scroll the screen if it does not fit.

For SSH you can edit the Banner parameter in the /etc/ssh/sshd_config file which will then appropriately display the banner text before the login prompt. For local console logins you can edit the /etc/issue file which will display the banner before the login prompt. For GDM, you could make the following changes to require a user to acknowledge the legal banner by selecting Yes or No. Edit the /etc/gdm/PreSession/Default file and add the following lines at the beginning of the script:

if ! gdialog --yesno '\nThis system is classified...\n' 10 10; then
    sleep 10
    exit 1;
fi

The This system is classified... test should be replaced with the valid text. It is important to note that this dialog will not prevent a login from progressing.

3.32 Miscellaneous

3.32.1 Host-Based Linux Monitoring and Intrusion Detection

Before you place a host into production or even on a network, consider the use of a system integrity checker, like seccheck (already discussed in Section 3.4, “Verifying Security Action with seccheck), so in case of unauthorized changes, notifications will be issued. Also consider the use of an intrusion detection environment, like AIDE, the Advanced Intrusion Detection Environment.

AIDE is a GPL licensed and open source intrusion detection system. It could be considered a system fingerprinting mechanism. AIDE works by creating a database containing information about the files on your system. The database is created from rules laid out in the configuration file aide.conf. When AIDE is run, this database is referenced to check for changes (or created for the first time). Assuming a comparison check is being run, any changes not permitted by the configuration file are reported.

By leveraging AIDE—storing a copy of the host's database in a secure location—and comparing it (on a scheduled basis or as part of a forensic effort), system integrity/insurance can be a matter of heuristics and procedure. If an intruder compromises your system, the comparison effort will enable an administrator or security officer to know what has changed on the host. The initial database should be created as a final step—before a system gets deployed into production.

It is outside the scope of this article to cover Linux Monitoring and detailed Intrusion Detection systems (IDS) or solutions, however there is a plethora of information about configuring AIDE or other solutions and many informative articles on the Web.

3.32.2 Connect Accounting Utilities

Here is a list of commands you can use to get data about user logins:

who Lists currently logged in users.

w Shows who is logged in and what they are doing.

last Shows a list of last logged in users, including login time, logout time, login IP address, etc.

lastb Same as last, except that by default it shows /var/log/btmp, which contains all the bad login attempts.

lastlog This command reports data maintained in /var/log/lastlog, which is a record of the last time a user logged in.

ac Available after installing the acct package. Prints the connect time in hours on a per-user basis or daily basis, etc. This command reads /var/log/wtmp.

dump-utmp Converts raw data from /var/run/utmp or /var/log/wtmp into ASCII-parsable format.

Also check the /var/log/messages file, or the output of journalctl if no logging facility is running. See Chapter 15, journalctl: Query the systemd Journal for more information on the systemd journal.

3.32.3 Other

Finally, the following items are relevant to the system security as well, and misconfiguration can cause many problems – and should be reviewed:

  • Resolver (/etc/hosts, /etc/resolv.conf, /etc/nsswitch.conf).

  • NTP configuration (/etc/ntp.conf).

A Documentation Updates

This chapter lists content changes for this document since the release of SUSE® Linux Enterprise Server 11 SP3.

This manual was updated on the following dates:

A.1 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)

All sections

Unified input line style.

Section 3.19, “Copying Files Using SSH Without Providing Login Prompts”

Replaced depricated ~/.ssh/authorized_keys2 and rsa-dss

Section 3.2, “Locking Down the BIOS”

Referenced UEFI

Section 3.29.2, “Restricting Use of Previous Passwords”

Fix configuration description (https://bugzilla.suse.com/show_bug.cgi?id=977984).

Section 3.25, “Restricting Access to Removable Media”

Name of rules files must start with a digit (Doc comment #29432).

Section 3.5, “Retiring Linux Servers with Sensitive Data”

More information about wiping files, wear leveling devices

Section 3.9.9, “Buffer Overflow Attack Mitigation”

Address Space Layout Randomization and No Execute bit do not prevent buffer overflows but buffer overflow attacks.

Bugfixes

PAM related fixes (https://bugzilla.suse.com/show_bug.cgi?id=978001, https://bugzilla.suse.com/show_bug.cgi?id=977984, https://bugzilla.suse.com/show_bug.cgi?id=977988).

A.2 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)

General
  • SMT Guide is now part of the documentation for SUSE Linux Enterprise Server.

  • Add-ons provided by SUSE have been renamed as modules and extensions. The manuals have been updated to reflect this change.

  • Numerous small fixes and additions to the documentation, based on technical feedback.

  • The registration service has been changed from Novell Customer Center to SUSE Customer Center.

  • In YaST, you will now reach Network Settings via the System group. Network Devices is gone (https://bugzilla.suse.com/show_bug.cgi?id=867809).

Bugfixes

A.3 February 2015 (Documentation Maintenance Update)

Bugfixes

A.4 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)

General
  • Removed all KDE documentation and references because KDE is no longer shipped.

  • Removed all references to SuSEconfig, which is no longer supported (Fate #100011).

  • Move from System V init to systemd (Fate #310421). Updated affected parts of the documentation.

  • YaST Runlevel Editor has changed to Services Manager (Fate #312568). Updated affected parts of the documentation.

  • Removed all references to ISDN support, as ISDN support has been removed (Fate #314594).

  • Removed all references to the YaST DSL module as it is no longer shipped (Fate #316264).

  • Removed all references to the YaST Modem module as it is no longer shipped (Fate #316264).

  • Btrfs has become the default file system for the root partition (Fate #315901). Updated affected parts of the documentation.

  • The dmesg now provides human-readable time stamps in ctime()-like format (Fate #316056). Updated affected parts of the documentation.

  • syslog and syslog-ng have been replaced by rsyslog (Fate #316175). Updated affected parts of the documentation.

  • MariaDB is now shipped as the relational database instead of MySQL (Fate #313595). Updated affected parts of the documentation.

  • SUSE-related products are no longer available from http://download.novell.com but from http://download.suse.com. Adjusted links accordingly.

  • Novell Customer Center has been replaced with SUSE Customer Center. Updated affected parts of the documentation.

  • /var/run is mounted as tmpfs (Fate #303793). Updated affected parts of the documentation.

  • The following architectures are no longer supported: IA64 and x86. Updated affected parts of the documentation.

  • The traditional method for setting up the network with ifconfig has been replaced by wicked. Updated affected parts of the documentation.

  • A lot of networking commands are deprecated and have been replaced by newer commands (usually ip). Updated affected parts of the documentation.

    arp: ip neighbor
    ifconfig: ip addr, ip link
    iptunnel: ip tunnel
    iwconfig: iw
    nameif: ip link, ifrename
    netstat: ss, ip route, ip -s link, ip maddr
    route: ip route
  • Numerous small fixes and additions to the documentation, based on technical feedback.

SUSE Linux Enterprise Server 12 SP3

Virtualization Guide

Describes virtualization technology in general, and introduces libvirt—the unified interface to virtualization—and detailed information on specific hypervisors.

Publication Date: April 04, 2018
About This Manual
Available Documentation
Feedback
Documentation Conventions
I Introduction
1 Virtualization Technology
1.1 Overview
1.2 Virtualization Capabilities
1.3 Virtualization Benefits
1.4 Virtualization Modes
1.5 I/O Virtualization
2 Introduction to Xen Virtualization
2.1 Basic Components
2.2 Xen Virtualization Architecture
3 Introduction to KVM Virtualization
3.1 Basic Components
3.2 KVM Virtualization Architecture
4 Introduction to Linux Containers
5 Virtualization Tools
5.1 Virtualization Console Tools
5.2 Virtualization GUI Tools
6 Installation of Virtualization Components
6.1 Installing KVM
6.2 Installing Xen
6.3 Installing Containers
6.4 Patterns
7 Supported Guests, Hosts and Features
7.1 Supported VM Guests
7.2 Supported VM Host Servers for SUSE Linux Enterprise Server 12 SP3 VM Guests
7.3 KVM Hardware Requirements
7.4 Feature Support
II Managing Virtual Machines with libvirt
8 Starting and Stopping libvirtd
9 Guest Installation
9.1 GUI-Based Guest Installation
9.2 Installing from the Command Line with virt-install
9.3 Advanced Guest Installation Scenarios
10 Basic VM Guest Management
10.1 Listing VM Guests
10.2 Accessing the VM Guest via Console
10.3 Changing a VM Guest's State: Start, Stop, Pause
10.4 Saving and Restoring the State of a VM Guest
10.5 Creating and Managing Snapshots
10.6 Deleting a VM Guest
10.7 Migrating VM Guests
10.8 Monitoring
11 Connecting and Authorizing
11.1 Authentication
11.2 Connecting to a VM Host Server
11.3 Configuring Remote Connections
12 Managing Storage
12.1 Managing Storage with Virtual Machine Manager
12.2 Managing Storage with virsh
12.3 Locking Disk Files and Block Devices with virtlockd
12.4 Online Resizing of Guest Block Devices
12.5 Sharing Directories between Host and Guests (File System Pass-Through)
12.6 Using RADOS Block Devices with libvirt
13 Managing Networks
13.1 Virtual Networks
13.2 Bridged Networking
14 Configuring Virtual Machines
14.1 Machine Setup
14.2 Storage
14.3 Controllers
14.4 Networking
14.5 Enabling Seamless and Synchronized Mouse Pointer Movement
14.6 Adding a CD/DVD-ROM Device with Virtual Machine Manager
14.7 Adding a Floppy Device with Virtual Machine Manager
14.8 Ejecting and Changing Floppy or CD/DVD-ROM Media with Virtual Machine Manager
14.9 Changing the Machine Type with virsh
14.10 Assigning a Host PCI Device to a VM Guest
14.11 Assigning a Host USB Device to a VM Guest
14.12 Adding SR-IOV Devices
14.13 Using Macvtap to Share VM Host Server Network Interfaces
III Hypervisor-Independent Features
15 Disk Cache Modes
15.1 Disk Interface Cache Modes
15.2 Description of Cache Modes
15.3 Data Integrity Implications of Cache Modes
15.4 Performance Implications of Cache Modes
15.5 Effect of Cache Modes on Live Migration
16 VM Guest Clock Settings
16.1 KVM: Using kvm_clock
16.2 Xen Virtual Machine Clock Settings
17 libguestfs
17.1 VM Guest Manipulation Overview
17.2 Package Installation
17.3 Guestfs Tools
17.4 Troubleshooting
17.5 External References
IV Managing Virtual Machines with Xen
18 Setting Up a Virtual Machine Host
18.1 Best Practices and Suggestions
18.2 Managing Dom0 Memory
18.3 Network Card in Fully Virtualized Guests
18.4 Starting the Virtual Machine Host
18.5 PCI Pass-Through
18.6 USB Pass-Through
19 Virtual Networking
19.1 Network Devices for Guest Systems
19.2 Host-Based Routing in Xen
19.3 Creating a Masqueraded Network Setup
19.4 Special Configurations
20 Managing a Virtualization Environment
20.1 XL—Xen Management Tool
20.2 Automatic Start of Guest Domains
20.3 Event Actions
20.4 Time Stamp Counter
20.5 Saving Virtual Machines
20.6 Restoring Virtual Machines
20.7 Virtual Machine States
21 Block Devices in Xen
21.1 Mapping Physical Storage to Virtual Disks
21.2 Mapping Network Storage to Virtual Disk
21.3 File-Backed Virtual Disks and Loopback Devices
21.4 Resizing Block Devices
21.5 Scripts for Managing Advanced Storage Scenarios
22 Virtualization: Configuration Options and Settings
22.1 Virtual CD Readers
22.2 Remote Access Methods
22.3 VNC Viewer
22.4 Virtual Keyboards
22.5 Dedicating CPU Resources
22.6 HVM Features
23 Administrative Tasks
23.1 The Boot Loader Program
23.2 Sparse Image Files and Disk Space
23.3 Migrating Xen VM Guest Systems
23.4 Monitoring Xen
23.5 Providing Host Information for VM Guest Systems
24 XenStore: Configuration Database Shared between Domains
24.1 Introduction
24.2 File System Interface
25 Xen as a High-Availability Virtualization Host
25.1 Xen HA with Remote Storage
25.2 Xen HA with Local Storage
25.3 Xen HA and Private Bridges
V Managing Virtual Machines with QEMU
26 QEMU Overview
27 Setting Up a KVM VM Host Server
27.1 CPU Support for Virtualization
27.2 Required Software
27.3 KVM Host-Specific Features
28 Guest Installation
28.1 Basic Installation with qemu-system-ARCH
28.2 Managing Disk Images with qemu-img
29 Running Virtual Machines with qemu-system-ARCH
29.1 Basic qemu-system-ARCH Invocation
29.2 General qemu-system-ARCH Options
29.3 Using Devices in QEMU
29.4 Networking in QEMU
29.5 Viewing a VM Guest with VNC
30 Virtual Machine Administration Using QEMU Monitor
30.1 Accessing Monitor Console
30.2 Getting Information about the Guest System
30.3 Changing VNC Password
30.4 Managing Devices
30.5 Controlling Keyboard and Mouse
30.6 Changing Available Memory
30.7 Dumping Virtual Machine Memory
30.8 Managing Virtual Machine Snapshots
30.9 Suspending and Resuming Virtual Machine Execution
30.10 Live Migration
30.11 QMP - QEMU Machine Protocol
VI Managing Virtual Machines with LXC
31 Linux Containers
31.1 Setting Up LXC Distribution Containers
31.2 Setting Up LXC Application Containers
31.3 Securing a Container Using AppArmor
31.4 Differences Between the libvirt LXC Driver and LXC
31.5 Sharing Namespaces Across Containers
31.6 For More Information
32 Migration from LXC to libvirt-lxc
32.1 Host Migration
32.2 Container Migration
32.3 Starting the Container
Glossary
A Virtual Machine Drivers
B Appendix
B.1 Installing Paravirtualized Drivers
B.2 Generating x509 Client/Server Certificates
C XM, XL Toolstacks and Libvirt framework
C.1 Xen Toolstacks
C.2 Import Xen Domain Configuration into libvirt
C.3 Differences Between the xm and xl Applications
C.4 External links
C.5 Saving a Xen Guest Configuration in an xm Compatible Format
D Documentation Updates
D.1 ??? 2018 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)
D.2 October 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)
D.3 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)
D.4 November 2016 (Release of SUSE Linux Enterprise Server 12 SP2)
D.5 March 2016 (Maintenance Release of SUSE Linux Enterprise Server 12 SP1)
D.6 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)
D.7 February 2015 (Documentation Maintenance Update)
D.8 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)
E GNU Licenses
E.1 GNU Free Documentation License

Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

About This Manual

  • Filename: kvm_intro.xml
  • ID: cha.kvm

This manual offers an introduction to setting up and managing virtualization with KVM (Kernel-based Virtual Machine), Xen, and Linux Containers (LXC) on SUSE Linux Enterprise Server. The first part introduces the different virtualization solutions by describing their requirements, their installations and SUSE's support status. The second part deals with managing VM Guests and VM Host Servers with libvirt. The following parts describe various administration tasks and practices and the last three parts deal with hypervisor-specific topics.

1 Available Documentation

  • Filename: common_intro_available_doc_i.xml
  • ID: no ID found
Note
Note: Online Documentation and Latest Updates

Documentation for our products is available at http://www.suse.com/documentation/, where you can also find the latest updates, and browse or download the documentation in various formats.

In addition, the product documentation is usually available in your installed system under /usr/share/doc/manual.

The following documentation is available for this product:

Installation Quick Start

Lists the system requirements and guides you step-by-step through the installation of SUSE Linux Enterprise Server from DVD, or from an ISO image.

Deployment Guide

Shows how to install single or multiple systems and how to exploit the product inherent capabilities for a deployment infrastructure. Choose from various approaches, ranging from a local installation or a network installation server to a mass deployment using a remote-controlled, highly-customized, and automated installation technique.

Administration Guide

Covers system administration tasks like maintaining, monitoring and customizing an initially installed system.

Virtualization Guide

Describes virtualization technology in general, and introduces libvirt—the unified interface to virtualization—and detailed information on specific hypervisors.

Storage Administration Guide

Provides information about how to manage storage devices on a SUSE Linux Enterprise Server.

AutoYaST

AutoYaST is a system for unattended mass deployment SUSE Linux Enterprise Server systems using an AutoYaST profile containing installation and configuration data. The manual guides you through the basic steps of auto-installation: preparation, installation, and configuration.

Security Guide

Introduces basic concepts of system security, covering both local and network security aspects. Shows how to use the product inherent security software like AppArmor or the auditing system that reliably collects information about any security-relevant events.

Security and Hardening Guide

Deals with the particulars of installing and setting up a secure SUSE Linux Enterprise Server, and additional post-installation processes required to further secure and harden that installation. Supports the administrator with security-related choices and decisions.

System Analysis and Tuning Guide

An administrator's guide for problem detection, resolution and optimization. Find how to inspect and optimize your system by means of monitoring tools and how to efficiently manage resources. Also contains an overview of common problems and solutions and of additional help and documentation resources.

SMT Guide

An administrator's guide to Subscription Management Tool—a proxy system for SUSE Customer Center with repository and registration targets. Learn how to install and configure a local SMT server, mirror and manage repositories, manage client machines, and configure clients to use SMT.

GNOME User Guide

Introduces the GNOME desktop of SUSE Linux Enterprise Server. It guides you through using and configuring the desktop and helps you perform key tasks. It is intended mainly for end users who want to make efficient use of GNOME as their default desktop.

2 Feedback

  • Filename: common_intro_feedback_i.xml
  • ID: no ID found

Several feedback channels are available:

Bugs and Enhancement Requests

For services and support options available for your product, refer to http://www.suse.com/support/.

Help for openSUSE is provided by the community. Refer to https://en.opensuse.org/Portal:Support for more information.

To report bugs for a product component, go to https://scc.suse.com/support/requests, log in, and click Create New.

User Comments

We want to hear your comments about and suggestions for this manual and the other documentation included with this product. Use the User Comments feature at the bottom of each page in the online documentation or go to http://www.suse.com/documentation/feedback.html and enter your comments there.

Mail

For feedback on the documentation of this product, you can also send a mail to doc-team@suse.com. Make sure to include the document title, the product version and the publication date of the documentation. To report errors or suggest enhancements, provide a concise description of the problem and refer to the respective section number and page (or URL).

3 Documentation Conventions

  • Filename: common_intro_typografie_i.xml
  • ID: no ID found

The following notices and typographical conventions are used in this documentation:

  • /etc/passwd: directory names and file names

  • PLACEHOLDER: replace PLACEHOLDER with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • package name : name of a package

  • Alt, AltF1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File › Save As: menu items, buttons

  • x86_64 This paragraph is only relevant for the AMD64/Intel 64 architecture. The arrows mark the beginning and the end of the text block.

    System z, POWER This paragraph is only relevant for the architectures z Systems and POWER. The arrows mark the beginning and the end of the text block.

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

  • Commands that must be run with root privileges. Often you can also prefix these commands with the sudo command to run them as non-privileged user.

    root # command
    tux > sudo command
  • Commands that can be run by non-privileged users.

    tux > command
  • Notices

    Warning
    Warning: Warning Notice

    Vital information you must be aware of before proceeding. Warns you about security issues, potential loss of data, damage to hardware, or physical hazards.

    Important
    Important: Important Notice

    Important information you should be aware of before proceeding.

    Note
    Note: Note Notice

    Additional information, for example about differences in software versions.

    Tip
    Tip: Tip Notice

    Helpful information, like a guideline or a piece of practical advice.

Part I Introduction

1 Virtualization Technology

Virtualization is a technology that provides a way for a machine (Host) to run another operating system (guest virtual machines) on top of the host operating system.

2 Introduction to Xen Virtualization

This chapter introduces and explains the components and technologies you need to understand to set up and manage a Xen-based virtualization environment.

3 Introduction to KVM Virtualization

4 Introduction to Linux Containers

Linux containers are a lightweight virtualization method to run multiple virtual units (containers) simultaneously on a single host. This is similar to the chroot environment. Containers are isolated with kernel Control Groups (cgroups) and kernel Namespaces.

5 Virtualization Tools

libvirt is a library that provides a common API for managing popular virtualization solutions, among them KVM, LXC, and Xen. The library provides a normalized management API for these virtualization solutions, allowing a stable, cross-hypervisor interface for higher-level management tools. The library also provides APIs for management of virtual networks and storage on the VM Host Server. The configuration of each VM Guest is stored in an XML file.

With libvirt you can also manage your VM Guests remotely. It supports TLS encryption, x509 certificates and authentication with SASL. This enables managing VM Host Servers centrally from a single workstation, alleviating the need to access each VM Host Server individually.

Using the libvirt-based tools is the recommended way of managing VM Guests. Interoperability between libvirt and libvirt-based applications has been tested and is an essential part of SUSE's support stance.

6 Installation of Virtualization Components

None of the virtualization tools is installed by default.

7 Supported Guests, Hosts and Features

Supported architectures and virtualization limits for Xen and KVM are outlined in the Release Notes.

1 Virtualization Technology

  • Filename: vt_introduction.xml
  • ID: chap.virtualization.introduction
Abstract

Virtualization is a technology that provides a way for a machine (Host) to run another operating system (guest virtual machines) on top of the host operating system.

1.1 Overview

SUSE Linux Enterprise Server includes the latest open source virtualization technologies, Xen and KVM. With these hypervisors, SUSE Linux Enterprise Server can be used to provision, de-provision, install, monitor and manage multiple virtual machines (VM Guests) on a single physical system (for more information see Hypervisor).

Out of the box, SUSE Linux Enterprise Server can create virtual machines running both modified, highly tuned, paravirtualized operating systems and fully virtualized unmodified operating systems. Full virtualization allows the guest OS to run unmodified and requires the presence of AMD64/Intel 64 processors which supports either Intel* Virtualization Technology (Intel VT) or AMD* Virtualization (AMD-V)).

The primary component of the operating system that enables virtualization is a hypervisor (or virtual machine manager), which is a layer of software that runs directly on server hardware. It controls platform resources, sharing them among multiple VM Guests and their operating systems by presenting virtualized hardware interfaces to each VM Guest.

SUSE Linux Enterprise is an enterprise-class Linux server operating system that offers two types of hypervisors: Xen and KVM. Both hypervisors support virtualization on the AMD64/Intel 64 architecture. For the POWER architecture KVM is supported. Both Xen and KVM support full virtualization mode. In addition, Xen supports paravirtualized mode. SUSE Linux Enterprise Server with Xen or KVM acts as a virtualization host server (VHS) that supports VM Guests with its own guest operating systems. The SUSE VM Guest architecture consists of a hypervisor and management components that constitute the VHS, which runs many application-hosting VM Guests.

In Xen, the management components run in a privileged VM Guest often called Dom0. In KVM, where the Linux kernel acts as the hypervisor, the management components run directly on the VHS.

1.2 Virtualization Capabilities

Virtualization design provides many capabilities to your organization. Virtualization of operating systems is used in many computing areas:

  • Server consolidation: Many servers can be replaced by one big physical server, so hardware is consolidated, and Guest Operating Systems are converted to virtual machine. It provides the ability to run legacy software on new hardware.

  • Isolation: guest operating system can be fully isolated from the Host running it. So if the virtual machine is corrupted, the Host system is not harmed.

  • Migration: A process to move a running virtual machine to another physical machine. Live migration is an extended feature that allows this move without disconnection of the client or the application.

  • Disaster recovery: Virtualized guests are less dependent on the hardware, and the Host server provides snapshot features to be able to restore a known running system without any corruption.

  • Dynamic load balancing: A migration feature that brings a simple way to load-balance your service across your infrastructure.

1.3 Virtualization Benefits

Virtualization brings a lot of advantages while providing the same service as a hardware server.

First, it reduces the cost of your infrastructure. Servers are mainly used to provide a service to a customer, and a virtualized operating system can provide the same service, with:

  • Less hardware: You can run several operating system on one host, so all hardware maintenance will be reduced.

  • Less power/cooling: Less hardware means you do not need to invest more in electric power, backup power, and cooling if you need more service.

  • Save space: Your data center space will be saved because you do not need more hardware servers (less servers than service running).

  • Less management: Using a VM Guest simplifies the administration of your infrastructure.

  • Agility and productivity: Virtualization provides migration capabilities, live migration and snapshots. These features reduce downtime, and bring an easy way to move your service from one place to another without any service interruption.

1.4 Virtualization Modes

Guest operating systems are hosted on virtual machines in either full virtualization (FV) mode or paravirtual (PV) mode. Each virtualization mode has advantages and disadvantages.

  • Full virtualization mode lets virtual machines run unmodified operating systems, such as Windows* Server 2003. It can use either Binary Translation or hardware-assisted virtualization technology, such as AMD* Virtualization or Intel* Virtualization Technology. Using hardware assistance allows for better performance on processors that support it.

    Some guest operating systems hosted in full virtualization mode can be configured to use drivers from the SUSE Virtual Machine Drivers Pack (VMDP) instead of drivers originating from the operating system. Running virtual machine drivers improves performance dramatically on guest operating systems, such as Windows Server 2003. For more information, see Appendix A, Virtual Machine Drivers.

  • To be able to run under paravirtual mode, guest operating systems usually need to be modified for the virtualization environment. However, operating systems running in paravirtual mode have better performance than those running under full virtualization.

    Operating systems currently modified to run in paravirtual mode are called paravirtualized operating systems and include SUSE Linux Enterprise Server and NetWare® 6.5 SP8.

1.5 I/O Virtualization

  • Filename: vt_io.xml
  • ID: sec.vt.io

VM Guests not only share CPU and memory resources of the host system, but also the I/O subsystem. Because software I/O virtualization techniques deliver less performance than bare metal, hardware solutions that deliver almost native performance have been developed recently. SUSE Linux Enterprise Server supports the following I/O virtualization techniques:

Full Virtualization

Fully Virtualized (FV) drivers emulate widely supported real devices, which can be used with an existing driver in the VM Guest. The guest is also called Hardware Virtual Machine (HVM). Since the physical device on the VM Host Server may differ from the emulated one, the hypervisor needs to process all I/O operations before handing them over to the physical device. Therefore all I/O operations need to traverse two software layers, a process that not only significantly impacts I/O performance, but also consumes CPU time.

Paravirtualization

Paravirtualization (PV) allows direct communication between the hypervisor and the VM Guest. With less overhead involved, performance is much better than with full virtualization. However, paravirtualization requires either the guest operating system to be modified to support the paravirtualization API or paravirtualized drivers. See Section 7.1.1, “Availability of Paravirtualized Drivers” for a list of guest operating systems supporting paravirtualization.

PVHVM

This type of virtualization enhances HVM (see Full Virtualization) with paravirtualized (PV) drivers, and PV interrupt and timer handling.

VFIO

VFIO stands for Virtual Function I/O and is a new user-level driver framework for Linux. It replaces the traditional KVM PCI Pass-Through device assignment. The VFIO driver exposes direct device access to user space in a secure memory (IOMMU) protected environment. With VFIO, a VM Guest can directly access hardware devices on the VM Host Server (pass-through), avoiding performance issues caused by emulation in performance critical paths. This method does not allow to share devices—each device can only be assigned to a single VM Guest. VFIO needs to be supported by the VM Host Server CPU, chipset and the BIOS/EFI.

Compared to the legacy KVM PCI device assignment, VFIO has the following advantages:

  • Resource access is compatible with secure boot.

  • Device is isolated and its memory access protected.

  • Offers a user space device driver with more flexible device ownership model.

  • Is independent of KVM technology, and not bound to x86 architecture only.

As of SUSE Linux Enterprise Server 12 SP2, the USB and PCI Pass-through methods of device assignment are considered deprecated and were superseded by the VFIO model.

SR-IOV

The latest I/O virtualization technique, Single Root I/O Virtualization SR-IOV combines the benefits of the aforementioned techniques—performance and the ability to share a device with several VM Guests. SR-IOV requires special I/O devices, that are capable of replicating resources so they appear as multiple separate devices. Each such pseudo device can be directly used by a single guest. However, for network cards for example the number of concurrent queues that can be used is limited, potentially reducing performance for the VM Guest compared to paravirtualized drivers. On the VM Host Server, SR-IOV must be supported by the I/O device, the CPU and chipset, the BIOS/EFI and the hypervisor—for setup instructions see Section 14.10, “Assigning a Host PCI Device to a VM Guest”.

Important
Important: Requirements for VFIO and SR-IOV

To be able to use the VFIO and SR-IOV features, the VM Host Server needs to fulfill the following requirements:

2 Introduction to Xen Virtualization

  • Filename: xen_virtualization_basics.xml
  • ID: cha.xen.basics

This chapter introduces and explains the components and technologies you need to understand to set up and manage a Xen-based virtualization environment.

2.1 Basic Components

The basic components of a Xen-based virtualization environment are the Xen hypervisor, the Dom0, any number of other VM Guests, and the tools, commands, and configuration files that let you manage virtualization. Collectively, the physical computer running all these components is called a VM Host Server because together these components form a platform for hosting virtual machines.

The Xen Hypervisor

The Xen hypervisor, sometimes simply called a virtual machine monitor, is an open source software program that coordinates the low-level interaction between virtual machines and physical hardware.

The Dom0

The virtual machine host environment, also called Dom0 or controlling domain, is composed of several components, such as:

  • SUSE Linux Enterprise Server provides a graphical and a command line environment to manage the virtual machine host components and its virtual machines.

    Note
    Note

    The term Dom0 refers to a special domain that provides the management environment. This may be run either in graphical or in command line mode.

  • The xl tool stack based on the xenlight library (libxl). Use it to manage Xen guest domains.

  • QEMU—an open source software that emulates a full computer system, including a processor and various peripherals. It provides the ability to host operating systems in both full virtualization or paravirtualization mode.

Xen-Based Virtual Machines

A Xen-based virtual machine, also called a VM Guest or DomU, consists of the following components:

  • At least one virtual disk that contains a bootable operating system. The virtual disk can be based on a file, partition, volume, or other type of block device.

  • A configuration file for each guest domain. It is a text file following the syntax described in the manual page man 5 xl.conf.

  • Several network devices, connected to the virtual network provided by the controlling domain.

Management Tools, Commands, and Configuration Files

There is a combination of GUI tools, commands, and configuration files to help you manage and customize your virtualization environment.

2.2 Xen Virtualization Architecture

The following graphic depicts a virtual machine host with four virtual machines. The Xen hypervisor is shown as running directly on the physical hardware platform. Note that the controlling domain is also a virtual machine, although it has several additional management tasks compared to all the other virtual machines.

Xen Virtualization Architecture
Figure 2.1: Xen Virtualization Architecture

On the left, the virtual machine host’s Dom0 is shown running the SUSE Linux Enterprise Server operating system. The two virtual machines shown in the middle are running paravirtualized operating systems. The virtual machine on the right shows a fully virtual machine running an unmodified operating system, such as the latest version of Microsoft Windows/Server.

3 Introduction to KVM Virtualization

  • Filename: kvm_virtualization_basics.xml
  • ID: cha.kvm.intro

3.1 Basic Components

KVM is a full virtualization solution for the AMD64/Intel 64 and the z Systems architectures supporting hardware virtualization.

VM Guests (virtual machines), virtual storage, and virtual networks can be managed with QEMU tools directly, or with the libvirt-based stack. The QEMU tools include qemu-system-ARCH, the QEMU monitor, qemu-img, and qemu-ndb. A libvirt-based stack includes libvirt itself, along with libvirt-based applications such as virsh, virt-manager, virt-install, and virt-viewer.

3.2 KVM Virtualization Architecture

This full virtualization solution consists of two main components:

  • A set of kernel modules (kvm.ko, kvm-intel.ko, and kvm-amd.ko) that provides the core virtualization infrastructure and processor-specific drivers.

  • A user space program (qemu-system-ARCH) that provides emulation for virtual devices and control mechanisms to manage VM Guests (virtual machines).

The term KVM more properly refers to the kernel level virtualization functionality, but is in practice more commonly used to refer to the user space component.

KVM Virtualization Architecture
Figure 3.1: KVM Virtualization Architecture
Note
Note: Hyper-V Emulation Support

QEMU can provide certain Hyper-V hypercalls for Windows* guests to partly emulate a Hyper-V environment. This can be used to achieve better behavior for Windows* guests that are Hyper-V enabled.

4 Introduction to Linux Containers

  • Filename: containers_basics.xml
  • ID: cha.containers.intro

Linux containers are a lightweight virtualization method to run multiple virtual units (containers) simultaneously on a single host. This is similar to the chroot environment. Containers are isolated with kernel Control Groups (cgroups) and kernel Namespaces.

Containers provide virtualization at the operating system level where the kernel controls the isolated containers. This is unlike full virtualization solutions like Xen or KVM where the processor simulates a complete hardware environment and controls virtual machines.

Conceptually, containers can be seen as an improved chroot technique. The difference is that a chroot environment separates only the file system, whereas containers go further and provide resource management and control via cgroups.

Benefits of Containers
  • Isolating applications and operating systems through containers.

  • Providing nearly native performance as container manages allocation of resources in real-time.

  • Controlling network interfaces and applying resources inside containers through cgroups.

Limitations of Containers
  • All containers run inside the host system's kernel and not with a different kernel.

  • Only allows Linux guest operating systems.

  • Security depends on the host system. Container is not secure. If you need a secure system, you can confine it using an AppArmor or SELinux profile.

5 Virtualization Tools

  • Filename: vt_tools.xml
  • ID: cha.tools.intro
Abstract

libvirt is a library that provides a common API for managing popular virtualization solutions, among them KVM, LXC, and Xen. The library provides a normalized management API for these virtualization solutions, allowing a stable, cross-hypervisor interface for higher-level management tools. The library also provides APIs for management of virtual networks and storage on the VM Host Server. The configuration of each VM Guest is stored in an XML file.

With libvirt you can also manage your VM Guests remotely. It supports TLS encryption, x509 certificates and authentication with SASL. This enables managing VM Host Servers centrally from a single workstation, alleviating the need to access each VM Host Server individually.

Using the libvirt-based tools is the recommended way of managing VM Guests. Interoperability between libvirt and libvirt-based applications has been tested and is an essential part of SUSE's support stance.

5.1 Virtualization Console Tools

The following libvirt-based tools for the command line are available on SUSE Linux Enterprise Server. All tools are provided by packages carrying the tool's name.

virsh

A command line tool to manage VM Guests with similar functionality as the Virtual Machine Manager. Allows you to change a VM Guest's status (start, stop, pause, etc.), to set up new guests and devices, or to edit existing configurations. virsh is also useful to script VM Guest management operations.

virsh takes the first argument as a command and further arguments as options to this command:

virsh [-c URI] COMMAND DOMAIN-ID [OPTIONS]

Like zypper, virsh can also be called without a command. In this case it starts a shell waiting for your commands. This mode is useful when having to run subsequent commands:

~> virsh -c qemu+ssh://wilber@mercury.example.com/system
Enter passphrase for key '/home/wilber/.ssh/id_rsa':
Welcome to virsh, the virtualization interactive terminal.

Type:  'help' for help with commands
       'quit' to quit

virsh # hostname
mercury.example.com
virt-install

A command line tool for creating new VM Guests using the libvirt library. It supports graphical installations via VNC or SPICE protocols. Given suitable command line arguments, virt-install can run completely unattended. This allows for easy automation of guest installs. virt-install is the default installation tool used by the Virtual Machine Manager.

5.2 Virtualization GUI Tools

The following libvirt-based graphical tools are available on SUSE Linux Enterprise Server. All tools are provided by packages carrying the tool's name.

Virtual Machine Manager (virt-manager)

The Virtual Machine Manager is a desktop tool for managing VM Guests. It provides the ability to control the life cycle of existing machines (start/shutdown, pause/resume, save/restore) and create new VM Guests. It allows managing various types of storage and virtual networks. It provides access to the graphical console of VM Guests with a built-in VNC viewer and can be used to view performance statistics. virt-manager supports connecting to a local libvirtd, managing a local VM Host Server, or a remote libvirtd managing a remote VM Host Server.

To start the Virtual Machine Manager, enter virt-manager at the command prompt.

Note
Note

To disable automatic USB device redirection for VM Guest using spice, either launch virt-manager with the --spice-disable-auto-usbredir parameter or run the following command to persistently change the default behavior:

tux > dconf write /org/virt-manager/virt-manager/console/auto-redirect false
virt-viewer

A viewer for the graphical console of a VM Guest. It uses SPICE (configured by default on the VM Guest) or VNC protocols and supports TLS and x509 certificates. VM Guests can be accessed by name, ID, or UUID. If the guest is not already running, the viewer can be told to wait until the guest starts, before attempting to connect to the console. virt-viewer is not installed by default and is available after installing the package virt-viewer.

Note
Note

To disable automatic USB device redirection for VM Guest using spice, add an empty filter using the --spice-usbredir-auto-redirect-filter='' parameter.

yast2 vm

A YaST module that simplifies the installation of virtualization tools and can set up a network bridge:

6 Installation of Virtualization Components

  • Filename: vt_installation.xml
  • ID: cha.vt.installation

None of the virtualization tools is installed by default.

6.1 Installing KVM

To install KVM and KVM tools, proceed as follows:

  1. Start YaST and choose Virtualization › Install Hypervisor and Tools.

  2. Select KVM server for a minimal installation of QEMU tools. Select KVM tools if a libvirt-based management stack is also desired. Confirm with Accept.

  3. To enable normal networking for the VM Guest, using a network bridge is recommended. YaST offers to automatically configure a bridge on the VM Host Server. Agree to do so by choosing Yes, otherwise choose No.

  4. After the setup has been finished, you can start setting up VM Guests. Rebooting the VM Host Server is not required.

6.2 Installing Xen

To install Xen and Xen tools, proceed as follows:

  1. Start YaST and choose Virtualization › Install Hypervisor and Tools.

  2. Select Xen server for a minimal installation of Xen tools. Select Xen tools if a libvirt-based management stack is also desired. Confirm with Accept.

  3. To enable normal networking for the VM Guest, using a network bridge is recommended. YaST offers to automatically configure a bridge on the VM Host Server. Agree to do so by choosing Yes, otherwise choose No.

  4. After the setup has been finished, you need to reboot the machine with the Xen kernel.

    Tip
    Tip: Default Boot Kernel

    If everything works as expected, change the default boot kernel with YaST and make the Xen-enabled kernel the default. For more information about changing the default kernel, see Section 12.3, “Configuring the Boot Loader with YaST”.

6.3 Installing Containers

To install containers, proceed as follows:

  1. Start YaST and choose Virtualization › Install Hypervisor and Tools.

  2. Select libvirt lxc daemon and confirm with Accept.

6.4 Patterns

It is possible using Zypper and patterns to install virtualization packages. Run the command zypper in -t pattern PATTERN. Available patterns are:

KVM
  • kvm_server: sets up the KVM VM Host Server with QEMU tools for management

  • kvm_tools: installs the libvirt tools for managing and monitoring VM Guests

Xen
  • xen_server: sets up the Xen VM Host Server with Xen tools for management

  • xen_tools: installs the libvirt tools for managing and monitoring VM Guests

Containers

There is no pattern for containers; install the libvirt-daemon-lxc package.

7 Supported Guests, Hosts and Features

  • Filename: virt_support.xml
  • ID: cha.virt.support

Supported architectures and virtualization limits for Xen and KVM are outlined in the Release Notes.

7.1 Supported VM Guests

This section lists the support status for various guest operating systems virtualized on top of SUSE Linux Enterprise Server 12 SP3. All guest operating systems are supported both fully-virtualized (FV in the following table) and paravirtualized (PV in the following table) with two exceptions: Windows, which is only supported fully-virtualized, and NetWare operating systems, which are only supported on Xen paravirtualized. All guest operating systems are supported both in 32-bit and 64-bit flavors, unless stated otherwise (see NetWare).

Table 7.1: Paravirtualized OS Support

Operating System

FV Support (Xen/KVM)

PV Support (Xen)

SLES 10 SP4

Full

Full

SLES 11 SP3

Full

Full

SLES 11 SP4

Full

Full

SLES 12

Full

Full

SLES 12 SP1

Full

Full

SLES 12 SP2

Full

Full

SLES 12 SP3

Full

Full

SLED 12 SP2

Technology preview1

Technology preview1

SLED 12 SP3

Technology preview1

Technology preview1

OES 11 SP3

Full

Full2

OES 2015

Full

Full2

OES 2015 SP1

Full

Full2

Netware 6.5 SP8

None

Full (32-bit only)2

RHEL 5.11+

Full/best effort3

Full/best effort3

RHEL 6.9+

Full/best effort3

Full/best effort3

RHEL 7.3+

Full/best effort3

Full/best effort3

Windows Server 2008 SP2+

Full

None

Windows Server 2008 R2 SP1+

Full

None

Windows Server 2012+

Full

None

Windows Server 2012 R2+

Full

None

Windows Server 2016

Full

None

Windows Vista SP2+

Best effort

None

Windows 7 SP1+

Best effort

None

Windows 8+

Best effort

None

Windows 8.1+

Best effort

None

Windows 10+

Best effort

None

1 Technology preview: The operating system has been tested to install and run successfully. Bugs can be reported and will be tracked by SUSE Technical Services, but no support commitments or service level agreements apply. Potential fixes and patches will be evaluated for future inclusion.
2 You need a static IP address for each virtual machine running NetWare or OES.
3 RedHat* guest operating systems are fully supported with Expanded Support. Otherwise, they will be supported on a best-effort basis (fixes if reasonable).

7.1.1 Availability of Paravirtualized Drivers

To improve the performance of the guest operating system, paravirtualized drivers are provided when available. Although they are not required, it is strongly recommended to use them. The paravirtualized drivers are available as follows:

SUSE Linux Enterprise Server 12 / 12 SP1 / 12 SP2

Included in kernel

SUSE Linux Enterprise Server 11 / 11 SP1 / 11 SP2 / 11 SP3 / 11 SP4

Included in kernel

SUSE Linux Enterprise Server 10 SP4

Included in kernel

RedHat

Available in RedHat Enterprise Linux 5.4 and newer

Windows

SUSE has developed virtio-based drivers for Windows, which are available in the Virtual Machine Driver Pack (VMDP). For more information, see http://www.suse.com/products/vmdriverpack/.

7.2 Supported VM Host Servers for SUSE Linux Enterprise Server 12 SP3 VM Guests

This section lists the support status of SUSE Linux Enterprise Server 12 SP3 running as a guest on top of various virtualization hosts (Hypervisor). Both 32-bit and 64-bit versions are supported for the host if available. The support status is defined as follows:

  • Full support for all SUSE host systems and SUSE Linux Enterprise Server 12 SP3 VM Guests

  • Full support for SUSE Linux Enterprise Server 12 SP3 VM Guests on third-party host systems

The following SUSE host operating systems are supported:

  • SUSE Linux Enterprise Server 11 SP4 (KVM/Xen)

  • SUSE Linux Enterprise Server 12 SP1 (KVM/Xen)

  • SUSE Linux Enterprise Server 12 SP2 (KVM/Xen)

The following third party host operating systems are supported:

  • KVM for IBM z Systems 1.1.0

  • PowerKVM

  • VMware ESX 5.5

  • VMware ESXi 6.0

  • Windows 2008 SP2+

  • Windows 2008 R2 SP1+

  • Windows 2012+

  • Windows 2012 R2+

  • Microsoft Windows 2016

  • Citrix XenServer 6.5

  • Oracle VM 3.3

The following host operating systems will be supported when released:

  • SUSE Linux Enterprise Server 12 SP3 (KVM/Xen)

  • VMware ESXi 2016

  • Citrix XenServer 6.5

7.3 KVM Hardware Requirements

Currently, SUSE only supports KVM full virtualization on AMD64/Intel 64 hosts and on z Systems (only as Technology Preview). On the AMD64/Intel 64 architecture, KVM is designed around hardware virtualization features included in AMD* (AMD-V) and Intel* (VT-x) CPUs. It supports virtualization features of chipsets, and PCI devices, such as an I/O Memory Mapping Unit (IOMMU) and Single Root I/O Virtualization (SR-IOV).

On the AMD64/Intel 64 architecture, you can test whether your CPU supports hardware virtualization with the following command:

egrep '(vmx|svm)' /proc/cpuinfo

If this command returns no output, your processor either does not support hardware virtualization, or this feature has been disabled in the BIOS or Firmware.

The following Web sites identify AMD64/Intel 64 processors that support hardware virtualization: http://ark.intel.com/Products/VirtualizationTechnology (for Intel CPUs), and http://products.amd.com/ (for AMD CPUs).

Note
Note: KVM Kernel Modules Not Loading

The KVM kernel modules only load if the CPU hardware virtualization features are available.

The general minimum hardware requirements for the VM Host Server are the same as outlined in Section 2.1, “System Requirements for Operating Linux”. However, additional RAM for each virtualized guest is needed. It should at least be the same amount that is needed for a physical installation. It is also strongly recommended to have at least one processor core or hyper-thread for each running guest.

7.4 Feature Support

7.4.1 Host (Dom0)

Table 7.2: Feature Support—Host (Dom0)

Features

Xen

Network and block device hotplugging

Yes

Physical CPU hotplugging

No

Virtual CPU hotplugging

Yes

Virtual CPU pinning

Yes

Virtual CPU capping

Yes

Intel* VT-x2: FlexPriority, FlexMigrate (migration constraints apply to dissimilar CPU architectures)

Yes

Intel* VT-d2 (DMA remapping with interrupt filtering and queued invalidation)

Yes

AMD* IOMMU (I/O page table with guest-to-host physical address translation)

Yes

Note
Note: Adding or Removing Physical CPUs at Runtime Is Not Supported

The addition or removal of physical CPUs at runtime is not supported. However, virtual CPUs can be added or removed for each VM Guest.

7.4.2 Paravirtualized Guest

Table 7.3: Feature Support—Paravirtualized Guest

Features

Xen

Virtual network and virtual block device hotplugging

Yes

Virtual CPU hotplugging

Yes

Virtual CPU over-commitment

Yes

Dynamic virtual memory resize

Yes

VM save and restore

Yes

VM live migration

Yes, between like virtual host systems with similar resources

Advanced debugging with GDBC

Yes

Dom0 metrics visible to VM

Yes

Memory ballooning

Yes

PCI pass-through

Yes (Netware guests are excluded)

For live migration, both source and target system architectures need to match; that is, the processors (AMD* or Intel*) must be the same. Unless CPU ID masking is used, such as with Intel FlexMigration, the target should feature the same processor revision or a more recent processor revision than the source. If VMs are moved among different systems, the same rules apply for each move. To avoid failing optimized code at runtime or application start-up, source and target CPUs need to expose the same processor extensions. Xen exposes the physical CPU extensions to the VMs transparently. To summarize, guests can be 32-bit or 64-bit, but the VHS must be identical.

Note
Note: Intel FlexMigration

For machines that support Intel FlexMigration, CPU-ID masking and faulting allow more flexibility in cross-CPU migration.

7.4.3 Fully Virtualized Guest

Table 7.4: Feature Support—Fully Virtualized Guest

Features

Xen

KVM

Virtual network and virtual block device hotplugging

Yes

Yes

Virtual CPU hotplugging

No

No

Virtual CPU over-commitment

Yes

Yes

Dynamic virtual memory resize

Yes

Yes

VM save and restore

Yes

Yes

VM Live Migration

Yes between like virtual host systems with similar resources (that is, from 32-bit to 32-bit, 64-bit to 64-bit)

Yes

VM snapshot

Yes

Yes

Advanced debugging with GDBC

Yes

Yes

Dom0 metrics visible to VM

Yes

Yes

PCI pass-through

Yes

Yes

Note
Note: Windows Guest

Hotplugging of virtual network and virtual block devices, and resizing, shrinking, and restoring dynamic virtual memory are supported in Xen and KVM only if PV drivers are being used (VMDP).

For KVM, a detailed description of supported limits, features, recommended settings and scenarios, and other useful information is maintained in kvm-supported.txt. This file is part of the KVM package and can be found in /usr/share/doc/packages/kvm.

Part II Managing Virtual Machines with libvirt

8 Starting and Stopping libvirtd

The communication between the virtualization solutions (KVM, Xen, LXC) and the libvirt API is managed by the daemon libvirtd. It needs to run on the VM Host Server. libvirt client applications such as virt-manager, possibly running on a remote machine, communicate with libvirtd running on the VM Hos…

9 Guest Installation

A VM Guest consists of an image containing an operating system and data files and a configuration file describing the VM Guest's virtual hardware resources. VM Guests are hosted on and controlled by the VM Host Server. This section provides generalized instructions for installing a VM Guest. For a l…

10 Basic VM Guest Management

Most management tasks, such as starting or stopping a VM Guest, can either be done using the graphical application Virtual Machine Manager or on the command line using virsh. Connecting to the graphical console via VNC is only possible from a graphical user interface.

11 Connecting and Authorizing

Managing several VM Host Servers, each hosting multiple VM Guests, quickly becomes difficult. One benefit of libvirt is the ability to connect to several VM Host Servers at once, providing a single interface to manage all VM Guests and to connect to their graphical console.

12 Managing Storage

When managing a VM Guest on the VM Host Server itself, you can access the complete file system of the VM Host Server to attach or create virtual hard disks or to attach existing images to the VM Guest. However, this is not possible when managing VM Guests from a remote host. For this reason, libvirt…

13 Managing Networks

This chapter introduces common networking configurations supported by libvirt. It does not depend on the hypervisor used. It is valid for all hypervisors supported by libvirt, such as KVM or Xen. These setups can be achieved using both the graphical interface of Virtual Machine Manager and the command line tool virsh.

14 Configuring Virtual Machines

Virtual Machine Manager's Details view offers in-depth information about the VM Guest's complete configuration and hardware equipment. Using this view, you can also change the guest configuration or add and modify virtual hardware. To access this view, open the guest's console in Virtual Machine Manager and either choose View › Details from the menu, or click Show virtual hardware details in the toolbar.

8 Starting and Stopping libvirtd

  • Filename: libvirt_overview.xml
  • ID: cha.libvirt.overview

The communication between the virtualization solutions (KVM, Xen, LXC) and the libvirt API is managed by the daemon libvirtd. It needs to run on the VM Host Server. libvirt client applications such as virt-manager, possibly running on a remote machine, communicate with libvirtd running on the VM Host Server, which services the request using native hypervisor APIs. Use the following commands to start and stop libvirtd or check its status:

tux > sudo systemctl start libvirtd

tux > sudo systemctl status libvirtd
libvirtd.service - Virtualization daemon
Loaded: loaded (/usr/lib/systemd/system/libvirtd.service; enabled)
Active: active (running) since Mon 2014-05-12 08:49:40 EDT; 2s ago
[...]

tux > sudo systemctl stop libvirtd

tux > sudo systemctl status libvirtd
[...]
Active: inactive (dead) since Mon 2014-05-12 08:51:11 EDT; 4s ago
[...]

To automatically start libvirtd at boot time, either activate it using the YaST Services Manager module or by entering the following command:

tux > sudo systemctl enable libvirtd
Important
Important: Conflicting Services: libvirtd and xendomains

If libvirtd fails to start, check if the service xendomains is loaded:

tux > systemctl is-active xendomains
active

If the command returns active, you need to stop xendomains before you can start the libvirtd daemon. If you want libvirtd to also start after rebooting, additionally prevent xendomains from starting automatically. Disable the service:

tux > sudo systemctl stop xendomains
tux > sudo systemctl disable xendomains
tux > sudo systemctl start libvirtd

xendomains and libvirtd provide the same service and when used in parallel may interfere with one another. As an example, xendomains may attempt to start a domU already started by libvirtd.

9 Guest Installation

  • Filename: libvirt_guest_installation.xml
  • ID: cha.kvm.inst

A VM Guest consists of an image containing an operating system and data files and a configuration file describing the VM Guest's virtual hardware resources. VM Guests are hosted on and controlled by the VM Host Server. This section provides generalized instructions for installing a VM Guest. For a list of supported VM Guests refer to Chapter 7, Supported Guests, Hosts and Features.

Virtual machines have few if any requirements above those required to run the operating system. If the operating system has not been optimized for the virtual machine host environment, it can only run on hardware-assisted virtualization computer hardware, in full virtualization mode, and requires specific device drivers to be loaded. The hardware that is presented to the VM Guest depends on the configuration of the host.

You should be aware of any licensing issues related to running a single licensed copy of an operating system on multiple virtual machines. Consult the operating system license agreement for more information.

9.1 GUI-Based Guest Installation

The New VM wizard helps you through the steps required to create a virtual machine and install its operating system. There are two ways to start it: Within Virtual Machine Manager, either click Create New Virtual Machine or choose File › New Virtual Machine. Alternatively, start YaST and choose Virtualization › Create Virtual Machines for Xen and KVM.

  1. Start the New VM wizard either from YaST or Virtual Machine Manager.

  2. Choose an installation source—either a locally available media or a network installation source. If you want to set up your VM Guest from an existing image, choose import existing disk image.

    On a VM Host Server running the Xen hypervisor, you can choose whether to install a paravirtualized or a fully virtualized guest. The respective option is available under Architecture Options. Depending on this choice, not all installation options may be available.

  3. Depending on your choice in the previous step, you need to provide the following data:

    Local Installation Media (ISO image or CDROM)

    Specify the path on the VM Host Server to an iso image containing the installation data. If it is available as a volume in a libvirt storage pool, you can also select it using Browse. For more information, see Chapter 12, Managing Storage.

    Alternatively, choose a physical CD-ROM or DVD inserted in the optical drive of the VM Host Server.

    Network Installation (HTTP, FTP, or NFS)

    Provide the URL pointing to the installation source. Valid URL prefixes are, for example, ftp://, http://, https://, and nfs://.

    Under URL Options, provide a path to an auto-installation file (AutoYaST or Kickstart, for example) and kernel parameters. Having provided a URL, the operating system should be automatically detected correctly. If this is not the case, deselect Automatically Detect Operating System Based on Install-Media and manually select the OS Type and Version.

    Network Boot (PXE)

    When booting via PXE, you only need to provide the OS Type and the Version.

    Import Existing Disk Image

    To set up the VM Guest from an existing image, you need to specify the path on the VM Host Server to the image. If it is available as a volume in a libvirt storage pool, you can also select it using Browse. For more information, see Chapter 12, Managing Storage.

  4. Choose the memory size and number of CPUs for the new virtual machine.

  5. This step is omitted when Import an Existing Image is chosen in the first step.

    Set up a virtual hard disk for the VM Guest. Either create a new disk image or choose an existing one from a storage pool (for more information, see Chapter 12, Managing Storage). If you choose to create a disk, a qcow2 image will be created. By default, it is stored under /var/lib/libvirt/images.

    Setting up a disk is optional. If you are running a live system directly from CD or DVD, for example, you can omit this step by deactivating Enable Storage for this Virtual Machine.

  6. On the last screen of the wizard, specify the name for the virtual machine. To be offered the possibility to review and make changes to the virtualized hardware selection, activate Customize configuration before install. Find options to specify the network device under Network Selection.

    Click Finish.

  7. (Optional) If you kept the defaults in the previous step, the installation will now start. If you selected Customize configuration before install, a VM Guest configuration dialog opens. For more information about configuring VM Guests, see Chapter 14, Configuring Virtual Machines.

    When you are done configuring, click Begin Installation.

Tip
Tip: Passing Key Combinations to Virtual Machines

The installation starts in a Virtual Machine Manager console window. Some key combinations, such as CtrlAltF1, are recognized by the VM Host Server but are not passed to the virtual machine. To bypass the VM Host Server, Virtual Machine Manager provides the sticky key functionality. Pressing Ctrl, Alt, or Shift three times makes the key sticky, then you can press the remaining keys to pass the combination to the virtual machine.

For example, to pass CtrlAltF2 to a Linux virtual machine, press Ctrl three times, then press AltF2. You can also press Alt three times, then press CtrlF2.

The sticky key functionality is available in the Virtual Machine Manager during and after installing a VM Guest.

9.2 Installing from the Command Line with virt-install

virt-install is a command line tool that helps you create new virtual machines using the libvirt library. It is useful if you cannot use the graphical user interface, or need to automatize the process of creating virtual machines.

virt-install is a complex script with a lot of command line switches. The following are required. For more information, see the man page of virt-install (1).

General Options
  • --name VM_GUEST_NAME: Specify the name of the new virtual machine. The name must be unique across all guests known to the hypervisor on the same connection. It is used to create and name the guest’s configuration file and you can access the guest with this name from virsh. Alphanumeric and _-.:+ characters are allowed.

  • --memory REQUIRED_MEMORY: Specify the amount of memory to allocate for the new virtual machine in megabytes.

  • --vcpus NUMBER_OF_CPUS: Specify the number of virtual CPUs. For best performance, the number of virtual processors should be less than or equal to the number of physical processors.

Virtualization Type
  • --paravirt: Set up a paravirtualized guest. This is the default if the VM Host Server supports paravirtualization and full virtualization.

  • --hvm: Set up a fully virtualized guest.

  • --virt-type HYPERVISOR: Specify the hypervisor. Supported values are kvm, xen, or lxc.

Guest Storage

Specify one of --disk, --filesystem or --nodisks the type of the storage for the new virtual machine. For example, --disk size=10 creates 10 GB disk in the default image location for the hypervisor and uses it for the VM Guest. --filesystem /export/path/on/vmhost specifies the directory on the VM Host Server to be exported to the guest. And --nodisks sets up a VM Guest without a local storage (good for Live CDs).

Installation Method

Specify the installation method using one of --location, --cdrom, --pxe, --import, or --boot .

Accessing the Installation

Use the --graphics VALUE option to specify how to access the installation. SUSE Linux Enterprise Server supports the values vnc or none.

If using vnc virt-install tries to launch virt-viewer. If it is not installed or cannot be run, connect to the VM Guest manually with you preferred viewer. To explicitly prevent virt-install from launching the viewer use --noautoconsole. To define a password for accessing the VNC session, use the following syntax: --graphics vnc,password=PASSWORD.

In case you are using --graphics none, you can access the VM Guest through operating system supported services, such as SSH or VNC. Refer to the operating system installation manual on how to set up these services in the installation system.

Enabling the Console

By default, the console is not enabled for new virtual machines installed using virt-install. To enable it, use --extra-args="console=ttyS0 textmode=1" as in the following example:

virt-install --virt-type kvm --name sles12 --memory 1024 \
 --disk /var/lib/libvirt/images/disk1.qcow2 --os-variant sles12
 --extra-args="console=ttyS0 textmode=1" --graphics none

After the installation finished, the /etc/default/grub file in the VM image will be updated with the console=ttyS0 option on the GRUB_CMDLINE_LINUX_DEFAULT line.

Example 9.1: Example of a virt-install command line

The following command line example creates a new SUSE Linux Enterprise Desktop 12 virtual machine with a virtio accelerated disk and network card. It creates a new 10 GB qcow2 disk image as a storage, the source installation media being the host CD-ROM drive. It will use VNC graphics, and it will auto-launch the graphical client.

KVM
virt-install --connect qemu:///system --virt-type kvm  --name sled12 \
--memory 1024 --disk size=10 --cdrom /dev/cdrom --graphics vnc \
--os-variant sled12
Xen
virt-install --connect xen:// --virt-type xen  --name sled12 \
--memory 1024 --disk size=10 --cdrom /dev/cdrom --graphics vnc \
--os-variant sled12

9.3 Advanced Guest Installation Scenarios

This section provides instructions for operations exceeding the scope of a normal installation, such as including modules and extensions packages.

9.3.1 Memory Ballooning with Windows Guests

Memory ballooning is a method to change the amount of memory used by VM Guest at runtime. Both the KVM and Xen hypervisors provide this method, but it needs to be supported by the guest as well.

While openSUSE and SLE-based guests support memory ballooning, Windows guests need the Virtual Machine Driver Pack (VMDP) to provide ballooning. To set the maximum memory greater than the initial memory configured for Windows guests, follow these steps:

  1. Install the Windows guest with the maximum memory equal or less than the initial value.

  2. Install the Virtual Machine Driver Pack in the Windows guest to provide required drivers.

  3. Shut down the Windows guest.

  4. Reset the maximum memory of the Windows guest to the required value.

  5. Start the Windows guest again.

9.3.2 Including Add-on Products in the Installation

Some operating systems such as SUSE Linux Enterprise Server offer to include add-on products in the installation process. In case the add-on product installation source is provided via network, no special VM Guest configuration is needed. If it is provided via CD/DVD or ISO image, it is necessary to provide the VM Guest installation system with both, the standard installation medium and an image for the add-on product.

In case you are using the GUI-based installation, select Customize Configuration Before Install in the last step of the wizard and add the add-on product ISO image via Add Hardware › Storage. Specify the path to the image and set the Device Type to CD-ROM.

If installing from the command line, you need to set up the virtual CD/DVD drives with the --disk parameter rather than with --cdrom. The device that is specified first is used for booting. The following example will install SUSE Linux Enterprise Server 12 plus SDK:

virt-install --name sles12+sdk --memory 1024 --disk size=10 \
--disk /virt/iso/SLES12.iso,device=cdrom \
--disk /virt/iso/SLES12_SDK.iso,device=cdrom \
--graphics vnc --os-variant sles12

10 Basic VM Guest Management

  • Filename: libvirt_managing.xml
  • ID: cha.libvirt.managing

Most management tasks, such as starting or stopping a VM Guest, can either be done using the graphical application Virtual Machine Manager or on the command line using virsh. Connecting to the graphical console via VNC is only possible from a graphical user interface.

Note
Note: Managing VM Guests on a Remote VM Host Server

If started on a VM Host Server, the libvirt tools Virtual Machine Manager, virsh, and virt-viewer can be used to manage VM Guests on the host. However, it is also possible to manage VM Guests on a remote VM Host Server. This requires configuring remote access for libvirt on the host. For instructions, see Chapter 11, Connecting and Authorizing.

To connect to such a remote host with Virtual Machine Manager, you need to set up a connection as explained in Section 11.2.2, “Managing Connections with Virtual Machine Manager”. If connecting to a remote host using virsh or virt-viewer, you need to specify a connection URI with the parameter -c (for example, virsh -c qemu+tls://saturn.example.com/system or virsh -c xen+ssh://). The form of connection URI depends on the connection type and the hypervisor—see Section 11.2, “Connecting to a VM Host Server” for details.

Examples in this chapter are all listed without a connection URI.

10.1 Listing VM Guests

The VM Guest listing shows all VM Guests managed by libvirt on a VM Host Server.

10.1.1 Listing VM Guests with Virtual Machine Manager

The main window of the Virtual Machine Manager lists all VM Guests for each VM Host Server it is connected to. Each VM Guest entry contains the machine's name, its status (Running, Paused, or Shutoff) displayed as an icon and literally, and a CPU usage bar.

10.1.2 Listing VM Guests with virsh

Use the command virsh list to get a list of VM Guests:

List all running guests
tux > virsh list
List all running and inactive guests
tux > virsh list --all

For more information and further options, see virsh help list or man 1 virsh.

10.2 Accessing the VM Guest via Console

VM Guests can be accessed via a VNC connection (graphical console) or, if supported by the guest operating system, via a serial console.

10.2.1 Opening a Graphical Console

Opening a graphical console to a VM Guest lets you interact with the machine like a physical host via a VNC connection. If accessing the VNC server requires authentication, you are prompted to enter a user name (if applicable) and a password.

When you click into the VNC console, the cursor is grabbed and cannot be used outside the console anymore. To release it, press AltCtrl.

Tip
Tip: Seamless (Absolute) Cursor Movement

To prevent the console from grabbing the cursor and to enable seamless cursor movement, add a tablet input device to the VM Guest. See Section 14.5, “Enabling Seamless and Synchronized Mouse Pointer Movement” for more information.

Certain key combinations such as CtrlAltDel are interpreted by the host system and are not passed to the VM Guest. To pass such key combinations to a VM Guest, open the Send Key menu from the VNC window and choose the desired key combination entry. The Send Key menu is only available when using Virtual Machine Manager and virt-viewer. With Virtual Machine Manager, you can alternatively use the sticky key feature as explained in Tip: Passing Key Combinations to Virtual Machines.

Note
Note: Supported VNC Viewers

Principally all VNC viewers can connect to the console of a VM Guest. However, if you are using SASL authentication and/or TLS/SSL connection to access the guest, the options are limited. Common VNC viewers such as tightvnc or tigervnc support neither SASL authentication nor TLS/SSL. The only supported alternative to Virtual Machine Manager and virt-viewer is Vinagre.

10.2.1.1 Opening a Graphical Console with Virtual Machine Manager

  1. In the Virtual Machine Manager, right-click a VM Guest entry.

  2. Choose Open from the pop-up menu.

10.2.1.2 Opening a Graphical Console with virt-viewer

virt-viewer is a simple VNC viewer with added functionality for displaying VM Guest consoles. For example, it can be started in wait mode, where it waits for a VM Guest to start before it connects. It also supports automatically reconnecting to a VM Guest that is rebooted.

virt-viewer addresses VM Guests by name, by ID or by UUID. Use virsh list --all to get this data.

To connect to a guest that is running or paused, use either the ID, UUID, or name. VM Guests that are shut off do not have an ID—you can only connect to them by UUID or name.

Connect to guest with the ID 8
tux > virt-viewer 8
Connect to the inactive guest named sles12; the connection window will open once the guest starts
tux > virt-viewer --wait sles12

With the --wait option, the connection will be upheld even if the VM Guest is not running at the moment. When the guest starts, the viewer will be launched.

For more information, see virt-viewer --help or man 1 virt-viewer.

Note
Note: Password Input on Remote connections with SSH

When using virt-viewer to open a connection to a remote host via SSH, the SSH password needs to be entered twice. The first time for authenticating with libvirt, the second time for authenticating with the VNC server. The second password needs to be provided on the command line where virt-viewer was started.

10.2.2 Opening a Serial Console

Accessing the graphical console of a virtual machine requires a graphical environment on the client accessing the VM Guest. As an alternative, virtual machines managed with libvirt can also be accessed from the shell via the serial console and virsh. To open a serial console to a VM Guest named sles12, run the following command:

tux > virsh console sles12

virsh console takes two optional flags: --safe ensures exclusive access to the console, --force disconnects any existing sessions before connecting. Both features need to be supported by the guest operating system.

Being able to connect to a VM Guest via serial console requires that the guest operating system supports serial console access and is properly supported. Refer to the guest operating system manual for more information.

Tip
Tip: Enabling Serial Console Access for SUSE Linux Enterprise and openSUSE Guests

Serial console access in SUSE Linux Enterprise and openSUSE is disabled by default. To enable it, proceed as follows:

SLES 12 / openSUSE

Launch the YaST Boot Loader module and switch to the Kernel Parameters tab. Add console=ttyS0 to the field Optional Kernel Command Line Parameter.

SLES 11

Launch the YaST Boot Loader module and select the boot entry for which to activate serial console access. Choose Edit and add console=ttyS0 to the field Optional Kernel Command Line Parameter. Additionally, edit /etc/inittab and uncomment the line with the following content:

#S0:12345:respawn:/sbin/agetty -L 9600 ttyS0 vt102

10.3 Changing a VM Guest's State: Start, Stop, Pause

Starting, stopping or pausing a VM Guest can be done with either Virtual Machine Manager or virsh. You can also configure a VM Guest to be automatically started when booting the VM Host Server.

When shutting down a VM Guest, you may either shut it down gracefully, or force the shutdown. The latter is equivalent to pulling the power plug on a physical host and is only recommended if there are no alternatives. Forcing a shutdown may cause file system corruption and loss of data on the VM Guest.

Tip
Tip: Graceful Shutdown

To be able to perform a graceful shutdown, the VM Guest must be configured to support ACPI. If you have created the guest with the Virtual Machine Manager, ACPI should be available in the VM Guest.

Depending on the guest operating system, availability of ACPI may not be sufficient to perform a graceful shutdown. It is strongly recommended to test shutting down and rebooting a guest before using it in production. openSUSE or SUSE Linux Enterprise Desktop, for example, can require PolKit authorization for shutdown and reboot. Make sure this policy is turned off on all VM Guests.

If ACPI was enabled during a Windows XP/Windows Server 2003 guest installation, turning it on in the VM Guest configuration only is not sufficient. For more information, see:

Regardless of the VM Guest's configuration, a graceful shutdown is always possible from within the guest operating system.

10.3.1 Changing a VM Guest's State with Virtual Machine Manager

Changing a VM Guest's state can be done either from Virtual Machine Manager's main window, or from a VNC window.

Procedure 10.1: State Change from the Virtual Machine Manager Window
  1. Right-click a VM Guest entry.

  2. Choose Run, Pause, or one of the Shutdown options from the pop-up menu.

Procedure 10.2: State change from the VNC Window
  1. Open a VNC Window as described in Section 10.2.1.1, “Opening a Graphical Console with Virtual Machine Manager”.

  2. Choose Run, Pause, or one of the Shut Down options either from the toolbar or from the Virtual Machine menu.

10.3.1.1 Automatically Starting a VM Guest

You can automatically start a guest when the VM Host Server boots. This feature is not enabled by default and needs to be enabled for each VM Guest individually. There is no way to activate it globally.

  1. Double-click the VM Guest entry in Virtual Machine Manager to open its console.

  2. Choose View › Details to open the VM Guest configuration window.

  3. Choose Boot Options and check Start virtual machine on host boot up.

  4. Save the new configuration with Apply.

10.3.2 Changing a VM Guest's State with virsh

In the following examples, the state of a VM Guest named sles12 is changed.

Start
tux > virsh start sles12
Pause
tux > virsh suspend sles12
Resume (a Suspended VM Guest)
tux > virsh resume sles12
Reboot
tux > virsh reboot sles12
Graceful shutdown
tux > virsh shutdown sles12
Force shutdown
tux > virsh destroy sles12
Turn on automatic start
tux > virsh autostart sles12
Turn off automatic start
tux > virsh autostart --disable sles12

10.4 Saving and Restoring the State of a VM Guest

Saving a VM Guest preserves the exact state of the guest’s memory. The operation is similar to hibernating a computer. A saved VM Guest can be quickly restored to its previously saved running condition.

When saved, the VM Guest is paused, its current memory state is saved to disk, and then the guest is stopped. The operation does not make a copy of any portion of the VM Guest’s virtual disk. The amount of time taken to save the virtual machine depends on the amount of memory allocated. When saved, a VM Guest’s memory is returned to the pool of memory available on the VM Host Server.

The restore operation loads a VM Guest’s previously saved memory state file and starts it. The guest is not booted but instead resumed at the point where it was previously saved. The operation is similar to coming out of hibernation.

The VM Guest is saved to a state file. Make sure there is enough space on the partition you are going to save to. For an estimation of the file size in megabytes to be expected, issue the following command on the guest:

tux > free -mh | awk '/^Mem:/ {print $3}'
Warning
Warning: Always Restore Saved Guests

After using the save operation, do not boot or start the saved VM Guest. Doing so would cause the machine's virtual disk and the saved memory state to get out of synchronization. This can result in critical errors when restoring the guest.

To be able to work with a saved VM Guest again, use the restore operation. If you used virsh to save a VM Guest, you cannot restore it using Virtual Machine Manager. In this case, make sure to restore using virsh.

Important
Important: Only for VM Guests with Disk Types raw, qcow2, qed

Saving and restoring VM Guests is only possible if the VM Guest is using a virtual disk of the type raw (.img), qcow2, or qed.

10.4.1 Saving/Restoring with Virtual Machine Manager

Procedure 10.3: Saving a VM Guest
  1. Open a VNC connection window to a VM Guest. Make sure the guest is running.

  2. Choose Virtual Machine › Shutdown › Save.

Procedure 10.4: Restoring a VM Guest
  1. Open a VNC connection window to a VM Guest. Make sure the guest is not running.

  2. Choose Virtual Machine › Restore.

    If the VM Guest was previously saved using Virtual Machine Manager, you will not be offered an option to Run the guest. However, note the caveats on machines saved with virsh outlined in Warning: Always Restore Saved Guests.

10.4.2 Saving and Restoring with virsh

Save a running VM Guest with the command virsh save and specify the file which it is saved to.

Save the guest named opensuse13
tux > virsh save opensuse13 /virtual/saves/opensuse13.vmsav
Save the guest with the ID 37
tux > virsh save 37 /virtual/saves/opensuse13.vmsave

To restore a VM Guest, use virsh restore:

tux > virsh restore /virtual/saves/opensuse13.vmsave

10.5 Creating and Managing Snapshots

VM Guest snapshots are snapshots of the complete virtual machine including the state of CPU, RAM, devices, and the content of all writable disks. To use virtual machine snapshots, all the attached hard disks need to use the qcow2 disk image format, and at least one of them needs to be writeable.

Snapshots let you restore the state of the machine at a particular point in time. This is useful when undoing a faulty configuration or the installation of a lot of packages. After starting a snapshot that was created while the VM Guest was shut off, you will need to boot it. Any changes written to the disk after that point in time will be lost when starting the snapshot.

Note
Note

Snapshots are supported on KVM VM Host Servers only.

10.5.1 Terminology

There are several specific terms used to describe the type of snapshots:

Internal snapshots

Snapshots that are saved into the qcow2 file of the original VM Guest. The file holds both the saved state of the snapshot and the changes made since the snapshot was taken. The main advantage of internal snapshots is that they are all stored in one file an therefore it is easy to copy or move them across multiple machines.

External snapshots

When creating an external snapshot, the original qcow2 file is saved and made read-only, while a new qcow2 file is created to hold the changes. The original file is sometimes called a 'backing' or 'base' file, while the new file with all the changes is called an 'overlay' or 'derived' file. External snapshots are useful when performing backups of VM Guests. For more information on external snapshots in QEMU, refer to Section 28.2.4, “Manipulate Disk Images Effectively”.

Live snapshots

Snapshots created when the original VM Guest is running. Internal live snapshots support saving the devices, and memory and disk states, while external live snapshots with virsh support saving either the memory state, or the disk state, or both.

Offline snapshots

Snapshot created from a VM Guest that is shut off. This ensures data integrity as all the guest's processes are stopped and no memory is in use.

10.5.2 Creating and Managing Snapshots with Virtual Machine Manager

Important
Important: Internal Snapshots Only

Virtual Machine Manager supports only internal snapshots, both live and offline.

To open the snapshot management view in Virtual Machine Manager, open the VNC window as described in Section 10.2.1.1, “Opening a Graphical Console with Virtual Machine Manager”. Now either choose View › Snapshots or click Manage VM Snapshots in the toolbar.

The list of existing snapshots for the chosen VM Guest is displayed in the left-hand part of the window. The snapshot that was last started is marked with a green tick. The right-hand part of the window shows details of the snapshot currently marked in the list. These details include the snapshot's title and time stamp, the state of the VM Guest at the time the snapshot was taken and a description. Snapshots of running guests also include a screenshot. The Description can be changed directly from this view. Other snapshot data cannot be changed.

10.5.2.1 Creating a Snapshot

To take a new snapshot of a VM Guest, proceed as follows:

  1. Optionally, shut down the VM Guest if you want to create an offline snapshot.

  2. Click Add in the bottom left corner of the VNC window.

    The window Create Snapshot opens.

  3. Provide a Name and, optionally, a description. The name cannot be changed after the snapshot has been taken. To be able to identify the snapshot later easily, use a speaking name.

  4. Confirm with Finish.

10.5.2.2 Deleting a Snapshot

To delete a snapshot of a VM Guest, proceed as follows:

  1. Click Delete in the bottom left corner of the VNC window.

  2. Confirm the deletion with Yes.

10.5.2.3 Starting a Snapshot

To start a snapshot, proceed as follows:

  1. Click Run in the bottom left corner of the VNC window.

  2. Confirm the start with Yes.

10.5.3 Creating and Managing Snapshots with virsh

To list all existing snapshots for a domain (admin_server in the following), run the snapshot-list command:

tux > virsh snapshot-list --domain admin_server
 Name                 Creation Time             State
------------------------------------------------------------
 Basic installation incl. SMT finished 2013-09-18 09:45:29 +0200 shutoff
 Basic installation incl. SMT for CLOUD3 2013-12-11 15:11:05 +0100 shutoff
 Basic installation incl. SMT for CLOUD3-HA 2014-03-24 13:44:03 +0100 shutoff
 Basic installation incl. SMT for CLOUD4 2014-07-07 11:27:47 +0200 shutoff
 Beta1 Running        2013-07-12 12:27:28 +0200 shutoff
 Beta2 prepared       2013-07-12 17:00:44 +0200 shutoff
 Beta2 running        2013-07-29 12:14:11 +0200 shutoff
 Beta3 admin node deployed 2013-07-30 16:50:40 +0200 shutoff
 Beta3 prepared       2013-07-30 17:07:35 +0200 shutoff
 Beta3 running        2013-09-02 16:13:25 +0200 shutoff
 Cloud2 GM running    2013-12-10 15:44:58 +0100 shutoff
 CLOUD3 RC prepared   2013-12-20 15:30:19 +0100 shutoff
 CLOUD3-HA Build 680 prepared 2014-03-24 14:20:37 +0100 shutoff
 CLOUD3-HA Build 796 installed (zypper up) 2014-04-14 16:45:18 +0200 shutoff
 GMC2 post Cloud install 2013-09-18 10:53:03 +0200 shutoff
 GMC2 pre Cloud install 2013-09-18 10:31:17 +0200 shutoff
 GMC2 prepared (incl. Add-On Installation) 2013-09-17 16:22:37 +0200 shutoff
 GMC_pre prepared     2013-09-03 13:30:38 +0200 shutoff
 OS + SMT + eth[01]   2013-06-14 16:17:24 +0200 shutoff
 OS + SMT + Mirror + eth[01] 2013-07-30 15:50:16 +0200 shutoff

The snapshot that was last started is shown with the snapshot-current command:

tux > virsh snapshot-current --domain admin_server
Basic installation incl. SMT for CLOUD4

Details about a particular snapshot can be obtained by running the snapshot-info command:

tux > virsh snapshot-info --domain admin_server \
   -name  "Basic installation incl. SMT for CLOUD4"
Name:           Basic installation incl. SMT for CLOUD4
Domain:         admin_server
Current:        yes
State:          shutoff
Location:       internal
Parent:         Basic installation incl. SMT for CLOUD3-HA
Children:       0
Descendants:    0
Metadata:       yes

10.5.3.1 Creating Internal Snapshots

To take an internal snapshot of a VM Guest, both live and offline, use the snapshot-create-as command as follows:

tux > virsh snapshot-create-as --domain admin_server1 --name "Snapshot 1"2 \
--description "First snapshot"3

1

Domain name. Mandatory.

2

Name of the snapshot. It is recommended to use a speaking name, since that makes it easier to identify the snapshot. Mandatory.

3

Description for the snapshot. Optional.

10.5.3.2 Creating External Snapshots

With virsh, you can take external snapshots of the guest's memory state, disk state, or both.

To take both live and offline external snapshot of the guest's disk, specify the --disk-only option:

tux > virsh snapshot-create-as --domain admin_server --name \
 "Offline external snapshot" --disk-only

You can specify the --diskspec option to control how the external files are created:

tux > virsh snapshot-create-as --domain admin_server --name \
 "Offline external snapshot" \
 --disk-only --diskspec vda,snapshot=external,file=/path/to/snapshot_file

To take a live external snapshot of the guest's memory, specify the --live and --memspec options:

tux > virsh snapshot-create-as --domain admin_server --name \
 "Offline external snapshot" --live \
 --memspec snapshot=external,file=/path/to/snapshot_file

To take a live external snapshot of both the guest's disk and memory states, combine the --live, --diskspec, and --memspec options:

tux > virsh snapshot-create-as --domain admin_server --name \
 "Offline external snapshot" --live \
 --memspec snapshot=external,file=/path/to/snapshot_file
 --diskspec vda,snapshot=external,file=/path/to/snapshot_file

Refer to the SNAPSHOT COMMANDS section in man 1 virsh for more details.

10.5.3.3 Deleting a Snapshot

To delete a snapshot of a VM Guest and restore the disk space it occupies, use the snapshot-delete command:

tux > virsh snapshot-delete --domain admin_server --snapshotname "Snapshot 2"

10.5.3.4 Starting a Snapshot

To start a snapshot, use the snapshot-revert command:

tux > virsh snapshot-revert --domain admin_server --snapshotname "Snapshot 1"

To start the current snapshot (the one the VM Guest was started off), it is sufficient to use --current rather than specifying the snapshot name:

tux > virsh snapshot-revert --domain admin_server --current

10.6 Deleting a VM Guest

By default, deleting a VM Guest using virsh removes only its XML configuration. Since attached storage is not deleted by default, you can reuse it with another VM Guest. With Virtual Machine Manager, you can also delete a guest's storage files as well—this will completely erase the guest.

10.6.1 Deleting a VM Guest with Virtual Machine Manager

  1. In the Virtual Machine Manager, right-click a VM Guest entry.

  2. From the context menu, choose Delete.

  3. A confirmation window opens. Clicking Delete will permanently erase the VM Guest. The deletion is not recoverable.

    You can also permanently delete the guest's virtual disk by activating Delete Associated Storage Files. The deletion is not recoverable either.

10.6.2 Deleting a VM Guest with virsh

To delete a VM Guest, it needs to be shut down first. It is not possible to delete a running guest. For information on shutting down, see Section 10.3, “Changing a VM Guest's State: Start, Stop, Pause”.

To delete a VM Guest with virsh, run virsh undefine VM_NAME.

tux > virsh undefine sles12

There is no option to automatically delete the attached storage files. If they are managed by libvirt, delete them as described in Section 12.2.4, “Deleting Volumes from a Storage Pool”.

10.7 Migrating VM Guests

One of the major advantages of virtualization is that VM Guests are portable. When a VM Host Server needs to go down for maintenance, or when the host gets overloaded, the guests can easily be moved to another VM Host Server. KVM and Xen even support live migrations during which the VM Guest is constantly available.

10.7.1 Migration Requirements

To successfully migrate a VM Guest to another VM Host Server, the following requirements need to be met:

  • It is recommended that the source and destination systems have the same architecture. However, it is possible to migrate between hosts with AMD* and Intel* architectures.

  • Storage devices must be accessible from both machines (for example, via NFS or iSCSI) and must be configured as a storage pool on both machines. For more information, see Chapter 12, Managing Storage.

    This is also true for CD-ROM or floppy images that are connected during the move. However, you can disconnect them prior to the move as described in Section 14.8, “Ejecting and Changing Floppy or CD/DVD-ROM Media with Virtual Machine Manager”.

  • libvirtd needs to run on both VM Host Servers and you must be able to open a remote libvirt connection between the target and the source host (or vice versa). Refer to Section 11.3, “Configuring Remote Connections” for details.

  • If a firewall is running on the target host, ports need to be opened to allow the migration. If you do not specify a port during the migration process, libvirt chooses one from the range 49152:49215. Make sure that either this range (recommended) or a dedicated port of your choice is opened in the firewall on the target host.

  • Host and target machine should be in the same subnet on the network, otherwise networking will not work after the migration.

  • No running or paused VM Guest with the same name must exist on the target host. If a shut down machine with the same name exists, its configuration will be overwritten.

  • All CPU models except host cpu model are supported when migrating VM Guests.

  • SATA disk device type is not migratable.

  • File system pass-through feature is incompatible with migration.

  • The VM Host Server and VM Guest need to have proper timekeeping installed. See Chapter 16, VM Guest Clock Settings.

  • No physical devices can be passed from host to guest. Live migration is currently not supported when using devices with PCI pass-through or SR-IOV. If live migration needs to be supported, you need to use software virtualization (paravirtualization or full virtualization).

  • Cache mode setting is an important setting for migration. See: Section 15.5, “Effect of Cache Modes on Live Migration”.

  • Live migration of VM Guests from a host running one operating system to a host running a different operating system is fully supported for the following scenarios:

    • SLES 12 SP1 to SLES 12 SP2;

    • SLES 12 SP2 to SLES 12 SP2

    • SLES 12 SP2 to SLES 12 SP3 (when released)

    Backward migration (for example from SLES 12 SP1 or SP2 to 12 or from SLES SP2 to SP1) is not supported.

    Live migration between SLE 11 and SLE 12 is not supported because of a different tool stack.

  • The image directory should be located in the same path on both hosts.

10.7.2 Migrating with Virtual Machine Manager

When using the Virtual Machine Manager to migrate VM Guests, it does not matter on which machine it is started. You can start Virtual Machine Manager on the source or the target host or even on a third host. In the latter case you need to be able to open remote connections to both the target and the source host.

  1. Start Virtual Machine Manager and establish a connection to the target or the source host. If the Virtual Machine Manager was started neither on the target nor the source host, connections to both hosts need to be opened.

  2. Right-click the VM Guest that you want to migrate and choose Migrate. Make sure the guest is running or paused—it is not possible to migrate guests that are shut down.

    Tip
    Tip: Increasing the Speed of the Migration

    To increase the speed of the migration somewhat, pause the VM Guest. This is the equivalent of the former so-called offline migration option of Virtual Machine Manager.

  3. Choose a New Host for the VM Guest. If the desired target host does not show up, make sure that you are connected to the host.

    To change the default options for connecting to the remote host, under Connection, set the Mode, and the target host's Address (IP address or host name) and Port. If you specify a Port, you must also specify an Address.

    Under Advanced options, choose whether the move should be permanent (default) or temporary, using Temporary move.

    Additionally, there is the option Allow unsafe, which allows migrating without disabling the cache of the VM Host Server. This can speed up the migration but only works when the current configuration allows for a consistent view of the VM Guest storage without using cache="none"/0_DIRECT.

    Note
    Note: Bandwidth Option

    In recent versions of Virtual Machine Manager, the option of setting a bandwidth for the migration has been removed. To set a specific bandwidth, use virsh instead.

  4. To perform the migration, click Migrate.

    When the migration is complete, the Migrate window closes and the VM Guest is now listed on the new host in the Virtual Machine Manager window. The original VM Guest will still be available on the target host (in shut down state).

10.7.3 Migrating with virsh

To migrate a VM Guest with virsh migrate, you need to have direct or remote shell access to the VM Host Server, because the command needs to be run on the host. The migration command looks like this:

tux > virsh migrate [OPTIONS] VM_ID_or_NAME CONNECTION_URI [--migrateuri tcp://REMOTE_HOST:PORT]

The most important options are listed below. See virsh help migrate for a full list.

--live

Does a live migration. If not specified, the guest will be paused during the migration (offline migration).

--suspend

Does an offline migration and does not restart the VM Guest on the target host.

--persistent

By default a migrated VM Guest will be migrated temporarily, so its configuration is automatically deleted on the target host if it is shut down. Use this switch to make the migration persistent.

--undefinesource

When specified, the VM Guest definition on the source host will be deleted after a successful migration (however, virtual disks attached to this guest will not be deleted).

The following examples use mercury.example.com as the source system and jupiter.example.com as the target system; the VM Guest's name is opensuse131 with Id 37.

Offline migration with default parameters
tux > virsh migrate 37 qemu+ssh://tux@jupiter.example.com/system
Transient live migration with default parameters
tux > virsh migrate --live opensuse131 qemu+ssh://tux@jupiter.example.com/system
Persistent live migration; delete VM definition on source
tux > virsh migrate --live --persistent --undefinesource 37 \
qemu+tls://tux@jupiter.example.com/system
Offline migration using port 49152
tux > virsh migrate opensuse131 qemu+ssh://tux@jupiter.example.com/system \
--migrateuri tcp://@jupiter.example.com:49152
Note
Note: Transient Compared to Persistent Migrations

By default virsh migrate creates a temporary (transient) copy of the VM Guest on the target host. A shut down version of the original guest description remains on the source host. A transient copy will be deleted from the server after it is shut down.

To create a permanent copy of a guest on the target host, use the switch --persistent. A shut down version of the original guest description remains on the source host, too. Use the option --undefinesource together with --persistent for a real move where a permanent copy is created on the target host and the version on the source host is deleted.

It is not recommended to use --undefinesource without the --persistent option, since this will result in the loss of both VM Guest definitions when the guest is shut down on the target host.

10.7.4 Step-by-Step Example

10.7.4.1 Exporting the Storage

First you need to export the storage, to share the Guest image between host. This can be done by an NFS server. In the following example we want to share the /volume1/VM directory for all machines that are on the network 10.0.1.0/24. We will use a SUSE Linux Enterprise NFS server. As root user, edit the /etc/exports file and add:

/volume1/VM 10.0.1.0/24  (rw,sync,no_root_squash)

You need to restart the NFS server:

tux > sudo systemctl restart nfsserver
tux > sudo exportfs
/volume1/VM      10.0.1.0/24

10.7.4.2 Defining the Pool on the Target Hosts

On each host where you want to migrate the VM Guest, the pool must be defined to be able to access the volume (that contains the Guest image). Our NFS server IP address is 10.0.1.99, its share is the /volume1/VM directory, and we want to get it mounted in the /var/lib/libvirt/images/VM directory. The pool name will be VM. To define this pool, create a VM.xml file with the following content:

<pool type='netfs'>
  <name>VM</name>
  <source>
    <host name='10.0.1.99'/>
    <dir path='/volume1/VM'/>
    <format type='auto'/>
  </source>
  <target>
    <path>/var/lib/libvirt/images/VM</path>
    <permissions>
      <mode>0755</mode>
      <owner>-1</owner>
      <group>-1</group>
    </permissions>
  </target>
  </pool>

Then load it into libvirt using the pool-define command:

root # virsh pool-define VM.xml

An alternative way to define this pool is to use the virsh command:

root # virsh pool-define-as VM --type netfs --source-host 10.0.1.99 \
     --source-path /volume1/VM --target /var/lib/libvirt/images/VM
Pool VM created

The following commands assume that you are in the interactive shell of virsh which can also be reached by using the command virsh without any arguments. Then the pool can be set to start automatically at host boot (autostart option):

virsh # pool-autostart VM
Pool VM marked as autostarted

If you want to disable the autostart:

virsh # pool-autostart VM --disable
Pool VM unmarked as autostarted

Check if the pool is present:

virsh # pool-list --all
 Name                 State      Autostart
-------------------------------------------
 default              active     yes
 VM                   active     yes

virsh # pool-info VM
Name:           VM
UUID:           42efe1b3-7eaa-4e24-a06a-ba7c9ee29741
State:          running
Persistent:     yes
Autostart:      yes
Capacity:       2,68 TiB
Allocation:     2,38 TiB
Available:      306,05 GiB
Warning
Warning: Pool Needs to Exist on All Target Hosts

Remember: this pool must be defined on each host where you want to be able to migrate your VM Guest.

10.7.4.3 Creating the Volume

The pool has been defined—now we need a volume which will contain the disk image:

virsh # vol-create-as VM sled12.qcow12 8G --format qcow2
Vol sled12.qcow12 created

The volume names shown will be used later to install the guest with virt-install.

10.7.4.4 Creating the VM Guest

Let's create a SUSE Linux Enterprise Server VM Guest with the virt-install command. The VM pool will be specified with the --disk option, cache=none is recommended if you do not want to use the --unsafe option while doing the migration.

root # virt-install --connect qemu:///system --virt-type kvm --name \
   sled12 --memory 1024 --disk vol=VM/sled12.qcow2,cache=none --cdrom \
   /mnt/install/ISO/SLE-12-Desktop-DVD-x86_64-Build0327-Media1.iso --graphics \
   vnc --os-variant sled12
Starting install...
Creating domain...

10.7.4.5 Migrate the VM Guest

Everything is ready to do the migration now. Run the migrate command on the VM Host Server that is currently hosting the VM Guest, and choose the destination.

virsh # migrate --live sled12 --verbose qemu+ssh://IP/Hostname/system
Password:
Migration: [ 12 %]

10.8 Monitoring

10.8.1 Monitoring with Virtual Machine Manager

After starting Virtual Machine Manager and connecting to the VM Host Server, a CPU usage graph of all the running guests is displayed.

It is also possible to get information about disk and network usage with this tool, however, you must first activate this in Preferences:

  1. Run virt-manager.

  2. Select Edit › Preferences.

  3. Change the tab from General to Polling.

  4. Activate the check boxes for the kind of activity you want to see: Poll Disk I/O, Poll Network I/O, and Poll Memory stats.

  5. If desired, also change the update interval using Update status every n seconds.

  6. Close the Preferences dialog.

  7. Activate the graphs that should be displayed under View › Graph.

Afterward, the disk and network statistics are also displayed in the main window of the Virtual Machine Manager.

More precise data is available from the VNC window. Open a VNC window as described in Section 10.2.1, “Opening a Graphical Console”. Choose Details from the toolbar or the View menu. The statistics are displayed from the Performance entry of the left-hand tree menu.

10.8.2 Monitoring with virt-top

virt-top is a command line tool similar to the well-known process monitoring tool top. virt-top uses libvirt and therefore is capable of showing statistics for VM Guests running on different hypervisors. It is recommended to use virt-top instead of hypervisor-specific tools like xentop.

By default virt-top shows statistics for all running VM Guests. Among the data that is displayed is the percentage of memory used (%MEM) and CPU (%CPU) and the uptime of the guest (TIME). The data is updated regularly (every three seconds by default). The following shows the output on a VM Host Server with seven VM Guests, four of them inactive:

virt-top 13:40:19 - x86_64 8/8CPU 1283MHz 16067MB 7.6% 0.5%
7 domains, 3 active, 3 running, 0 sleeping, 0 paused, 4 inactive D:0 O:0 X:0
CPU: 6.1%  Mem: 3072 MB (3072 MB by guests)

   ID S RDRQ WRRQ RXBY TXBY %CPU %MEM    TIME   NAME
    7 R  123    1  18K  196  5.8  6.0   0:24.35 sled12_sp1
    6 R    1    0  18K    0  0.2  6.0   0:42.51 sles12_sp1
    5 R    0    0  18K    0  0.1  6.0  85:45.67 opensuse_leap
    -                                           (Ubuntu_1410)
    -                                           (debian_780)
    -                                           (fedora_21)
    -                                           (sles11sp3)

By default the output is sorted by ID. Use the following key combinations to change the sort field:

ShiftP: CPU usage
ShiftM: Total memory allocated by the guest
ShiftT: Time
ShiftI: ID

To use any other field for sorting, press ShiftF and select a field from the list. To toggle the sort order, use ShiftR.

virt-top also supports different views on the VM Guests data, which can be changed on-the-fly by pressing the following keys:

0: default view
1: show physical CPUs
2: show network interfaces
3: show virtual disks

virt-top supports more hot keys to change the view of the data and many command line switches that affect the behavior of the program. For more information, see man 1 virt-top.

10.8.3 Monitoring with kvm_stat

kvm_stat can be used to trace KVM performance events. It monitors /sys/kernel/debug/kvm, so it needs the debugfs to be mounted. On SUSE Linux Enterprise Server it should be mounted by default. In case it is not mounted, use the following command:

tux > sudo mount -t debugfs none /sys/kernel/debug

kvm_stat can be used in three different modes:

kvm_stat                    # update in 1 second intervals
kvm_stat -1                 # 1 second snapshot
kvm_stat -l > kvmstats.log  # update in 1 second intervals in log format
                            # can be imported to a spreadsheet
Example 10.1: Typical Output of kvm_stat
kvm statistics

 efer_reload                  0       0
 exits                 11378946  218130
 fpu_reload               62144     152
 halt_exits              414866     100
 halt_wakeup             260358      50
 host_state_reload       539650     249
 hypercalls                   0       0
 insn_emulation         6227331  173067
 insn_emulation_fail          0       0
 invlpg                  227281      47
 io_exits                113148      18
 irq_exits               168474     127
 irq_injections          482804     123
 irq_window               51270      18
 largepages                   0       0
 mmio_exits                6925       0
 mmu_cache_miss           71820      19
 mmu_flooded              35420       9
 mmu_pde_zapped           64763      20
 mmu_pte_updated              0       0
 mmu_pte_write           213782      29
 mmu_recycled                 0       0
 mmu_shadow_zapped       128690      17
 mmu_unsync                  46      -1
 nmi_injections               0       0
 nmi_window                   0       0
 pf_fixed               1553821     857
 pf_guest               1018832     562
 remote_tlb_flush        174007      37
 request_irq                  0       0
 signal_exits                 0       0
 tlb_flush               394182     148
?????

See http://clalance.blogspot.com/2009/01/kvm-performance-tools.html for further information on how to interpret these values.

11 Connecting and Authorizing

  • Filename: libvirt_connect.xml
  • ID: cha.libvirt.connect

Managing several VM Host Servers, each hosting multiple VM Guests, quickly becomes difficult. One benefit of libvirt is the ability to connect to several VM Host Servers at once, providing a single interface to manage all VM Guests and to connect to their graphical console.

To ensure only authorized users can connect, libvirt offers several connection types (via TLS, SSH, Unix sockets, and TCP) that can be combined with different authorization mechanisms (socket, PolKit, SASL and Kerberos).

11.1 Authentication

The power to manage VM Guests and to access their graphical console is something that should be restricted to a well defined circle of persons. To achieve this goal, you can use the following authentication techniques on the VM Host Server:

  • Access control for Unix sockets with permissions and group ownership. This method is available for libvirtd connections only.

  • Access control for Unix sockets with PolKit. This method is available for local libvirtd connections only.

  • User name and password authentication with SASL (Simple Authentication and Security Layer). This method is available for both, libvirtd and VNC connections. Using SASL does not require real user accounts on the server, since it uses its own database to store user names and passwords. Connections authenticated with SASL are encrypted.

  • Kerberos authentication. This method, available for libvirtd connections only, is not covered in this manual. Refer to http://libvirt.org/auth.html#ACL_server_kerberos for details.

  • Single password authentication. This method is available for VNC connections only.

Important
Important: Authentication for libvirtd and VNC need to be configured separately

Access to the VM Guest's management functions (via libvirtd) on the one hand, and to its graphical console on the other hand, always needs to be configured separately. When restricting access to the management tools, these restrictions do not automatically apply to VNC connections!

When accessing VM Guests from remote via TLS/SSL connections, access can be indirectly controlled on each client by restricting read permissions to the certificate's key file to a certain group. See Section 11.3.2.5, “Restricting Access (Security Considerations)” for details.

11.1.1 libvirtd Authentication

libvirtd authentication is configured in /etc/libvirt/libvirtd.conf. The configuration made here applies to all libvirt tools such as the Virtual Machine Manager or virsh.

libvirt offers two sockets: a read-only socket for monitoring purposes and a read-write socket to be used for management operations. Access to both sockets can be configured independently. By default, both sockets are owned by root.root. Default access permissions on the read-write socket are restricted to the user root (0700) and fully open on the read-only socket (0777).

In the following instructions, you will learn how to configure access permissions for the read-write socket. The same instructions also apply to the read-only socket. All configuration steps need to be carried out on the VM Host Server.

Note
Note: Default Authentication Settings on SUSE Linux Enterprise Server

The default authentication method on SUSE Linux Enterprise Server is access control for Unix sockets. Only the user root may authenticate. When accessing the libvirt tools as a non-root user directly on the VM Host Server, you need to provide the root password through PolKit once. You are then granted access for the current and for future sessions.

Alternatively, you can configure libvirt to allow system access to non-privileged users. See Section 11.2.1, “system Access for Non-Privileged Users” for details.

11.1.1.1 Access Control for Unix Sockets with Permissions and Group Ownership

To grant access for non-root accounts, configure the sockets to be owned and accessible by a certain group (libvirt in the following example). This authentication method can be used for local and remote SSH connections.

  1. In case it does not exist, create the group that should own the socket:

    groupadd libvirt
    Important
    Important: Group Needs to Exist

    The group must exist prior to restarting libvirtd. If not, the restart will fail.

  2. Add the desired users to the group:

    usermod --append --groups libvirt tux
  3. Change the configuration in /etc/libvirt/libvirtd.conf as follows:

    unix_sock_group = "libvirt"1
    unix_sock_rw_perms = "0770"2
    auth_unix_rw = "none"3

    1

    Group ownership will be set to group libvirt.

    2

    Sets the access permissions for the socket (srwxrwx---).

    3

    Disables other authentication methods (PolKit or SASL). Access is solely controlled by the socket permissions.

  4. Restart libvirtd:

    systemctl start libvirtd

11.1.1.2 Local Access Control for Unix Sockets with PolKit

Access control for Unix sockets with PolKit is the default authentication method on SUSE Linux Enterprise Server for non-remote connections. Therefore, no libvirt configuration changes are needed. With PolKit authorization enabled, permissions on both sockets default to 0777 and each application trying to access a socket needs to authenticate via PolKit.

Important
Important: PolKit Authentication for Local Connections Only

Authentication with PolKit can only be used for local connections on the VM Host Server itself, since PolKit does not handle remote authentication.

Two policies for accessing libvirt's sockets exist:

  • org.libvirt.unix.monitor: accessing the read-only socket

  • org.libvirt.unix.manage: accessing the read-write socket

By default, the policy for accessing the read-write socket is to authenticate with the root password once and grant the privilege for the current and for future sessions.

To grant users access to a socket without having to provide the root password, you need to create a rule in /etc/polkit-1/rules.d. Create the file /etc/polkit-1/rules.d/10-grant-libvirt with the following content to grant access to the read-write socket to all members of the group libvirt:

polkit.addRule(function(action, subject) {
  if (action.id == "org.libvirt.unix.manage" && subject.isInGroup("libvirt")) {
    return polkit.Result.YES;
  }
});

11.1.1.3 User name and Password Authentication with SASL

SASL provides user name and password authentication and data encryption (digest-md5, by default). Since SASL maintains its own user database, the users do not need to exist on the VM Host Server. SASL is required by TCP connections and on top of TLS/SSL connections.

Important
Important: Plain TCP and SASL with digest-md5 Encryption

Using digest-md5 encryption on an otherwise not encrypted TCP connection does not provide enough security for production environments. It is recommended to only use it in testing environments.

Tip
Tip: SASL Authentication on Top of TLS/SSL

Access from remote TLS/SSL connections can be indirectly controlled on the client side by restricting access to the certificate's key file. However, this might prove error-prone when dealing with many clients. Using SASL with TLS adds security by additionally controlling access on the server side.

To configure SASL authentication, proceed as follows:

  1. Change the configuration in /etc/libvirt/libvirtd.conf as follows:

    1. To enable SASL for TCP connections:

      auth_tcp = "sasl"
    2. To enable SASL for TLS/SSL connections:

      auth_tls = "sasl"
  2. Restart libvirtd:

    systemctl restart libvirtd
  3. The libvirt SASL configuration file is located at /etc/sasl2/libvirtd.conf. Normally, there is no need to change the defaults. However, if using SASL on top of TLS, you may turn off session encryption to avoid additional overhead (TLS connections are already encrypted) by commenting the line setting the mech_list parameter. Only do this for TLS/SASL, for TCP connections this parameter must be set to digest-md5.

    #mech_list: digest-md5
  4. By default, no SASL users are configured, so no logins are possible. Use the following commands to manage users:

    Add the user tux
    saslpasswd2 -a libvirt tux
    Delete the user tux
    saslpasswd2 -a libvirt -d tux
    List existing users
    sasldblistusers2 -f /etc/libvirt/passwd.db
Tip
Tip: virsh and SASL Authentication

When using SASL authentication, you will be prompted for a user name and password every time you issue a virsh command. Avoid this by using virsh in shell mode.

11.1.2 VNC Authentication

Since access to the graphical console of a VM Guest is not controlled by libvirt, but rather by the specific hypervisor, it is always necessary to additionally configure VNC authentication. The main configuration file is /etc/libvirt/<hypervisor>.conf. This section describes the QEMU/KVM hypervisor, so the target configuration file is /etc/libvirt/qemu.conf.

Note
Note: VNC Authentication for Xen

In contrast to KVM and LXC, Xen does not yet offer more sophisticated VNC authentication than setting a password on a per VM basis. See the <graphics type='vnc'... libvirt configuration option below.

Two authentication types are available: SASL and single password authentication. If you are using SASL for libvirt authentication, it is strongly recommended to use it for VNC authentication as well—it is possible to share the same database.

A third method to restrict access to the VM Guest is to enable the use of TLS encryption on the VNC server. This requires the VNC clients to have access to x509 client certificates. By restricting access to these certificates, access can indirectly be controlled on the client side. Refer to Section 11.3.2.4.2, “VNC over TLS/SSL: Client Configuration” for details.

11.1.2.1 User name and Password Authentication with SASL

SASL provides user name and password authentication and data encryption. Since SASL maintains its own user database, the users do not need to exist on the VM Host Server. As with SASL authentication for libvirt, you may use SASL on top of TLS/SSL connections. Refer to Section 11.3.2.4.2, “VNC over TLS/SSL: Client Configuration” for details on configuring these connections.

To configure SASL authentication for VNC, proceed as follows:

  1. Create a SASL configuration file. It is recommended to use the existing libvirt file. If you have already configured SASL for libvirt and are planning to use the same settings including the same user name and password database, a simple link is suitable:

    ln -s /etc/sasl2/libvirt.conf /etc/sasl2/qemu.conf

    If are setting up SASL for VNC only or you are planning to use a different configuration than for libvirt, copy the existing file to use as a template:

    cp /etc/sasl2/libvirt.conf /etc/sasl2/qemu.conf

    Then edit it according to your needs.

  2. Change the configuration in /etc/libvirt/qemu.conf as follows:

    vnc_listen = "0.0.0.0"
    vnc_sasl = 1
    sasldb_path: /etc/libvirt/qemu_passwd.db

    The first parameter enables VNC to listen on all public interfaces (rather than to the local host only), and the second parameter enables SASL authentication.

  3. By default, no SASL users are configured, so no logins are possible. Use the following commands to manage users:

    Add the user tux
    saslpasswd2 -f /etc/libvirt/qemu_passwd.db -a qemu tux
    Delete the user tux
    saslpasswd2 -f /etc/libvirt/qemu_passwd.db -a qemu -d tux
    List existing users
    sasldblistusers2 -f /etc/libvirt/qemu_passwd.db
  4. Restart libvirtd:

    systemctl restart libvirtd
  5. Restart all VM Guests that have been running prior to changing the configuration. VM Guests that have not been restarted will not use SASL authentication for VNC connects.

Note
Note: Supported VNC Viewers

SASL authentication is currently supported by Virtual Machine Manager and virt-viewer. Both of these viewers also support TLS/SSL connections.

11.1.2.2 Single Password Authentication

Access to the VNC server may also be controlled by setting a VNC password. You can either set a global password for all VM Guests or set individual passwords for each guest. The latter requires to edit the VM Guest's configuration files.

Note
Note: Always Set a Global Password

If you are using single password authentication, it is good practice to set a global password even if setting passwords for each VM Guest. This will always leave your virtual machines protected with a fallback password if you forget to set a per-machine password. The global password will only be used if no other password is set for the machine.

Procedure 11.1: Setting a Global VNC Password
  1. Change the configuration in /etc/libvirt/qemu.conf as follows:

    vnc_listen = "0.0.0.0"
    vnc_password = "PASSWORD"

    The first parameter enables VNC to listen on all public interfaces (rather than to the local host only), and the second parameter sets the password. The maximum length of the password is eight characters.

  2. Restart libvirtd:

    root # systemctl restart libvirtd
  3. Restart all VM Guests that have been running prior to changing the configuration. VM Guests that have not been restarted will not use password authentication for VNC connects.

Procedure 11.2: Setting a VM Guest Specific VNC Password
  1. Change the configuration in /etc/libvirt/qemu.conf as follows to enable VNC to listen on all public interfaces (rather than to the local host only).

    vnc_listen = "0.0.0.0"
  2. Open the VM Guest's XML configuration file in an editor. Replace VM NAME in the following example with the name of the VM Guest. The editor that is used defaults to $EDITOR. If that variable is not set, vi is used.

    virsh edit VM NAME
  3. Search for the element <graphics> with the attribute type='vnc', for example:

    <graphics type='vnc' port='-1' autoport='yes'/>
  4. Add the passwd=PASSWORD attribute, save the file and exit the editor. The maximum length of the password is eight characters.

    <graphics type='vnc' port='-1' autoport='yes' passwd='PASSWORD'/>
  5. Restart libvirtd:

    root # systemctl restart libvirtd
  6. Restart all VM Guests that have been running prior to changing the configuration. VM Guests that have not been restarted will not use password authentication for VNC connects.

Warning
Warning: Security of the VNC Protocol

The VNC protocol is not considered to be safe. Although the password is sent encrypted, it might be vulnerable when an attacker can sniff both the encrypted password and the encryption key. Therefore, it is recommended to use VNC with TLS/SSL or tunneled over SSH. virt-viewer, Virtual Machine Manager and vinagre from version 2.30 onward support both methods.

11.2 Connecting to a VM Host Server

To connect to a hypervisor with libvirt, you need to specify a uniform resource identifier (URI). This URI is needed with virsh and virt-viewer (except when working as root on the VM Host Server) and is optional for the Virtual Machine Manager. Although the latter can be called with a connection parameter (for example, virt-manager -c qemu:///system), it also offers a graphical interface to create connection URIs. See Section 11.2.2, “Managing Connections with Virtual Machine Manager” for details.

HYPERVISOR1+PROTOCOL2://USER@REMOTE3/CONNECTION_TYPE4

1

Specify the hypervisor. SUSE Linux Enterprise Server currently supports the following hypervisors: test (dummy for testing), qemu (KVM), and xen (Xen). This parameter is mandatory.

2

When connecting to a remote host, specify the protocol here. It can be one of: ssh (connection via SSH tunnel), tcp (TCP connection with SASL/Kerberos authentication), tls (TLS/SSL encrypted connection with authentication via x509 certificates).

3

When connecting to a remote host, specify the user name and the remote host name. If no user name is specified, the user name that has called the command ($USER) is used. See below for more information. For TLS connections, the host name needs to be specified exactly as in the x509 certificate.

4

When connecting to the QEMU/KVM hypervisor, two connection types are accepted: system for full access rights, or session for restricted access. Since session access is not supported on SUSE Linux Enterprise Server, this documentation focuses on system access.

Example Hypervisor Connection URIs
test:///default

Connect to the local dummy hypervisor. Useful for testing.

qemu:///system or xen:///system

Connect to the QEMU/Xen hypervisor on the local host having full access (type system).

qemu+ssh://tux@mercury.example.com/system or xen+ssh://tux@mercury.example.com/system

Connect to the QEMU/Xen hypervisor on the remote host mercury.example.com. The connection is established via an SSH tunnel.

qemu+tls://saturn.example.com/system or xen+tls://saturn.example.com/system

Connect to the QEMU/Xen hypervisor on the remote host mercury.example.com. The connection is established using TLS/SSL.

For more details and examples, refer to the libvirt documentation at http://libvirt.org/uri.html.

Note
Note: User Names in URIs

A user name needs to be specified when using Unix socket authentication (regardless of whether using the user/password authentication scheme or PolKit). This applies to all SSH and local connections.

There is no need to specify a user name when using SASL authentication (for TCP or TLS connections) or when doing no additional server-side authentication for TLS connections. With SASL the user name will not be evaluated—you will be prompted for an SASL user/password combination in any case.

11.2.1 system Access for Non-Privileged Users

As mentioned above, a connection to the QEMU hypervisor can be established using two different protocols: session and system. A session connection is spawned with the same privileges as the client program. Such a connection is intended for desktop virtualization, since it is restricted (for example no USB/PCI device assignments, no virtual network setup, limited remote access to libvirtd).

The system connection intended for server virtualization has no functional restrictions but is, by default, only accessible by root. However, with the addition of the DAC (Discretionary Access Control) driver to libvirt it is now possible to grant non-privileged users system access. To grant system access to the user tux, proceed as follows:

Procedure 11.3: Granting system Access to a Regular User
  1. Enable access via Unix sockets as described in Section 11.1.1.1, “Access Control for Unix Sockets with Permissions and Group Ownership”. In that example access to libvirt is granted to all members of the group libvirt and tux made a member of this group. This ensures that tux can connect using virsh or Virtual Machine Manager.

  2. Edit /etc/libvirt/qemu.conf and change the configuration as follows:

    user = "tux"
    group = "libvirt"
    dynamic_ownership = 1

    This ensures that the VM Guests are started by tux and that resources bound to the guest (for example virtual disks) can be accessed and modified by tux.

  3. Make tux a member of the group kvm:

    usermod --append --groups kvm tux

    This step is needed to grant access to /dev/kvm, which is required to start VM Guests.

  4. Restart libvirtd:

    root # systemctl restart libvirtd

11.2.2 Managing Connections with Virtual Machine Manager

The Virtual Machine Manager uses a Connection for every VM Host Server it manages. Each connection contains all VM Guests on the respective host. By default, a connection to the local host is already configured and connected.

All configured connections are displayed in the Virtual Machine Manager main window. Active connections are marked with a small triangle, which you can click to fold or unfold the list of VM Guests for this connection.

Inactive connections are listed gray and are marked with Not Connected. Either double-click or right-click it and choose Connect from the context menu. You can also Delete an existing connection from this menu.

Note
Note: Editing Existing Connections

It is not possible to edit an existing connection. To change a connection, create a new one with the desired parameters and delete the old one.

To add a new connection in the Virtual Machine Manager, proceed as follows:

  1. Choose File › Add Connection

  2. Choose the host's Hypervisor (Xen or QEMU/KVM)

  3. (Optional) To set up a remote connection, choose Connect to remote host. For more information, see Section 11.3, “Configuring Remote Connections”.

    In case of a remote connection, specify the Hostname of the remote machine in the format USERNAME@REMOTE _HOST.

    Important
    Important: Specifying a User Name

    There is no need to specify a user name for TCP and TLS connections: In these cases, it will not be evaluated. However, in the case of SSH connections, specifying a user name is necessary when you want to connect as a user other than root.

  4. If you do not want the connection to be automatically started when starting the Virtual Machine Manager, deactivate Autoconnect.

  5. Finish the configuration by clicking Connect.

11.3 Configuring Remote Connections

A major benefit of libvirt is the ability to manage VM Guests on different remote hosts from a central location. This section gives detailed instructions on how to configure server and client to allow remote connections.

11.3.1 Remote Tunnel over SSH (qemu+ssh or xen+ssh)

Enabling a remote connection that is tunneled over SSH on the VM Host Server only requires the ability to accept SSH connections. Make sure the SSH daemon is started (systemctl status sshd) and that the ports for service SSH are opened in the firewall.

User authentication for SSH connections can be done using traditional file user/group ownership and permissions as described in Section 11.1.1.1, “Access Control for Unix Sockets with Permissions and Group Ownership”. Connecting as user tux (qemu+ssh://tuxsIVname;/system or xen+ssh://tuxsIVname;/system) works out of the box and does not require additional configuration on the libvirt side.

When connecting via SSH qemu+ssh://USER@SYSTEM or xen+ssh://USER@SYSTEM you need to provide the password for USER. This can be avoided by copying your public key to ~USER/.ssh/authorized_keys on the VM Host Server as explained in Section 14.5.2, “Copying an SSH Key”. Using an ssh-agent on the machine from which you are connecting adds even more convenience. For more information, see Section 14.5.3, “Using the ssh-agent.

11.3.2 Remote TLS/SSL Connection with x509 Certificate (qemu+tls or xen+tls)

Using TCP connections with TLS/SSL encryption and authentication via x509 certificates is much more complicated to set up than SSH, but it is a lot more scalable. Use this method if you need to manage several VM Host Servers with a varying number of administrators.

11.3.2.1 Basic Concept

TLS (Transport Layer Security) encrypts the communication between two computers by using certificates. The computer starting the connection is always considered the client, using a client certificate, while the receiving computer is always considered the server, using a server certificate. This scenario applies, for example, if you manage your VM Host Servers from a central desktop.

If connections are initiated from both computers, each needs to have a client and a server certificate. This is the case, for example, if you migrate a VM Guest from one host to another.

Each x509 certificate has a matching private key file. Only the combination of certificate and private key file can identify itself correctly. To assure that a certificate was issued by the assumed owner, it is signed and issued by a central certificate called certificate authority (CA). Both the client and the server certificates must be issued by the same CA.

Important
Important: User Authentication

Using a remote TLS/SSL connection only ensures that two computers are allowed to communicate in a certain direction. Restricting access to certain users can indirectly be achieved on the client side by restricting access to the certificates. For more information, see Section 11.3.2.5, “Restricting Access (Security Considerations)”.

libvirt also supports user authentication on the server with SASL. For more information, see Section 11.3.2.6, “Central User Authentication with SASL for TLS Sockets”.

11.3.2.2 Configuring the VM Host Server

The VM Host Server is the machine receiving connections. Therefore, the server certificates need to be installed. The CA certificate needs to be installed, too. When the certificates are in place, TLS support can be turned on for libvirt.

  1. Create the server certificate and export it together with the CA certificate as described in Section B.2, “Generating x509 Client/Server Certificates”.

  2. Create the following directories on the VM Host Server:

    mkdir -p /etc/pki/CA/ /etc/pki/libvirt/private/

    Install the certificates as follows:

    /etc/pki/CA/cacert.pem
    /etc/pki/libvirt/servercert.pem
    /etc/pki/libvirt/private/serverkey.pem
    Important
    Important: Restrict Access to Certificates

    Make sure to restrict access to certificates as explained in Section 11.3.2.5, “Restricting Access (Security Considerations)”.

  3. Enable TLS support by editing /etc/libvirt/libvirtd.conf and setting listen_tls = 1. Restart libvirtd:

    root # systemctl restart libvirtd
  4. By default, libvirt uses the TCP port 16514 for accepting secure TLS connections. Open this port in the firewall.

Important
Important: Restarting libvirtd with TLS enabled

If you enable TLS for libvirt, the server certificates need to be in place, otherwise restarting libvirtd will fail. You also need to restart libvirtd in case you change the certificates.

11.3.2.3 Configuring the Client and Testing the Setup

The client is the machine initiating connections. Therefore the client certificates need to be installed. The CA certificate needs to be installed, too.

  1. Create the client certificate and export it together with the CA certificate as described in Section B.2, “Generating x509 Client/Server Certificates”.

  2. Create the following directories on the client:

    mkdir -p /etc/pki/CA/ /etc/pki/libvirt/private/

    Install the certificates as follows:

    /etc/pki/CA/cacert.pem
    /etc/pki/libvirt/clientcert.pem
    /etc/pki/libvirt/private/clientkey.pem
    Important
    Important: Restrict Access to Certificates

    Make sure to restrict access to certificates as explained in Section 11.3.2.5, “Restricting Access (Security Considerations)”.

  3. Test the client/server setup by issuing the following command. Replace mercury.example.com with the name of your VM Host Server. Specify the same fully qualified host name as used when creating the server certificate.

    #QEMU/KVM
    virsh -c qemu+tls://mercury.example.com/system list --all
    
    #Xen
    virsh -c xen+tls://mercury.example.com/system list --all

    If your setup is correct, you will see a list of all VM Guests registered with libvirt on the VM Host Server.

11.3.2.4 Enabling VNC for TLS/SSL connections

Currently, VNC communication over TLS is only supported by a few tools. Common VNC viewers such as tightvnc or tigervnc do not support TLS/SSL. The only supported alternative to Virtual Machine Manager and virt-viewer is vinagre.

11.3.2.4.1 VNC over TLS/SSL: VM Host Server Configuration

To access the graphical console via VNC over TLS/SSL, you need to configure the VM Host Server as follows:

  1. Open ports for the service VNC in your firewall.

  2. Create a directory /etc/pki/libvirt-vnc and link the certificates into this directory as follows:

    mkdir -p /etc/pki/libvirt-vnc && cd /etc/pki/libvirt-vnc
            ln -s /etc/pki/CA/cacert.pem ca-cert.pem
            ln -s /etc/pki/libvirt/servercert.pem server-cert.pem
            ln -s /etc/pki/libvirt/private/serverkey.pem server-key.pem
  3. Edit /etc/libvirt/qemu.conf and set the following parameters:

    vnc_listen = "0.0.0.0"
            vnc_tls = 1
            vnc_tls_x509_verify = 1
  4. Restart the libvirtd:

    root # systemctl restart libvirtd
    Important
    Important: VM Guests Need to be Restarted

    The VNC TLS setting is only set when starting a VM Guest. Therefore, you need to restart all machines that have been running prior to making the configuration change.

11.3.2.4.2 VNC over TLS/SSL: Client Configuration

The only action needed on the client side is to place the x509 client certificates in a location recognized by the client of choice. Unfortunately, each supported client—Virtual Machine Manager, virt-viewer, and vinagre—expects the certificates in a different location. However, Virtual Machine Manager and vinagre can either read from a system-wide location applying to all users, or from a per-user location.

Virtual Machine Manager (virt-manager)

To connect to the remote host, Virtual Machine Manager requires the setup explained in Section 11.3.2.3, “Configuring the Client and Testing the Setup”. To be able to connect via VNC, the client certificates also need to be placed in the following locations:

System-wide location
/etc/pki/CA/cacert.pem
/etc/pki/libvirt-vnc/clientcert.pem
/etc/pki/libvirt-vnc/private/clientkey.pem
Per-user location
/etc/pki/CA/cacert.pem
~/.pki/libvirt-vnc/clientcert.pem
~/.pki/libvirt-vnc/private/clientkey.pem
virt-viewer

virt-viewer only accepts certificates from a system-wide location:

/etc/pki/CA/cacert.pem
/etc/pki/libvirt-vnc/clientcert.pem
/etc/pki/libvirt-vnc/private/clientkey.pem
Important
Important: Restrict Access to Certificates

Make sure to restrict access to certificates as explained in Section 11.3.2.5, “Restricting Access (Security Considerations)”.

11.3.2.5 Restricting Access (Security Considerations)

Each x509 certificate consists of two pieces: the public certificate and a private key. A client can only authenticate using both pieces. Therefore, any user that has read access to the client certificate and its private key can access your VM Host Server. On the other hand, an arbitrary machine equipped with the full server certificate can pretend to be the VM Host Server. Since this is probably not desirable, access to at least the private key files needs to be restricted as much as possible. The easiest way to control access to a key file is to use access permissions.

Server Certificates

Server certificates need to be readable for QEMU processes. On SUSE Linux Enterprise Server QEMU, processes started from libvirt tools are owned by root, so it is sufficient if the root can read the certificates:

chmod 700 /etc/pki/libvirt/private/
chmod 600 /etc/pki/libvirt/private/serverkey.pem

If you change the ownership for QEMU processes in /etc/libvirt/qemu.conf, you also need to adjust the ownership of the key file.

System Wide Client Certificates

To control access to a key file that is available system-wide, restrict read access to a certain group, so that only members of that group can read the key file. In the following example, a group libvirt is created, and group ownership of the clientkey.pem file and its parent directory is set to libvirt. Afterward, the access permissions are restricted to owner and group. Finally the user tux is added to the group libvirt, and thus can access the key file.

CERTPATH="/etc/pki/libvirt/"
# create group libvirt
groupadd libvirt
# change ownership to user root and group libvirt
chown root.libvirt $CERTPATH/private $CERTPATH/clientkey.pem
# restrict permissions
chmod 750 $CERTPATH/private
chmod 640 $CERTPATH/private/clientkey.pem
# add user tux to group libvirt
usermod --append --groups libvirt tux
Per-User Certificates

User-specific client certificates for accessing the graphical console of a VM Guest via VNC need to be placed in the user's home directory in ~/.pki. Contrary to SSH, for example, the VNC viewer using these certificates do not check the access permissions of the private key file. Therefore, it is solely the user's responsibility to make sure the key file is not readable by others.

11.3.2.5.1 Restricting Access from the Server Side

By default, every client that is equipped with appropriate client certificates may connect to a VM Host Server accepting TLS connections. Therefore, it is possible to use additional server-side authentication with SASL as described in Section 11.1.1.3, “User name and Password Authentication with SASL”.

It is also possible to restrict access with a whitelist of DNs (distinguished names), so only clients with a certificate matching a DN from the list can connect.

Add a list of allowed DNs to tls_allowed_dn_list in /etc/libvirt/libvirtd.conf. This list may contain wild cards. Do not specify an empty list, since that would result in refusing all connections.

tls_allowed_dn_list = [
   "C=US,L=Provo,O=SUSE Linux Products GmbH,OU=*,CN=venus.example.com,EMAIL=*",
   "C=DE,L=Nuremberg,O=SUSE Linux Products GmbH,OU=Documentation,CN=*"]

Get the distinguished name of a certificate with the following command:

certtool -i --infile /etc/pki/libvirt/clientcert.pem | grep "Subject:"

Restart libvirtd after having changed the configuration:

root # systemctl restart libvirtd

11.3.2.6 Central User Authentication with SASL for TLS Sockets

A direct user authentication via TLS is not possible—this is handled indirectly on each client via the read permissions for the certificates as explained in Section 11.3.2.5, “Restricting Access (Security Considerations)”. However, if a central, server-based user authentication is needed, libvirt also allows to use SASL (Simple Authentication and Security Layer) on top of TLS for direct user authentication. See Section 11.1.1.3, “User name and Password Authentication with SASL” for configuration details.

11.3.2.7 Troubleshooting

11.3.2.7.1 Virtual Machine Manager/virsh Cannot Connect to Server

Check the following in the given order:

Is it a firewall issue (TCP port 16514 needs to be open on the server)?
Is the client certificate (certificate and key) readable by the user that has started Virtual Machine Manager/virsh?
Has the same full qualified host name as in the server certificate been specified with the connection?
Is TLS enabled on the server (listen_tls = 1)?
Has libvirtd been restarted on the server?
11.3.2.7.2 VNC Connection fails

Ensure that you can connect to the remote server using Virtual Machine Manager. If so, check whether the virtual machine on the server has been started with TLS support. The virtual machine's name in the following example is sles.

ps ax | grep qemu | grep "\-name sles" | awk -F" -vnc " '{ print FS $2 }'

If the output does not begin with a string similar to the following, the machine has not been started with TLS support and must be restarted.

 -vnc 0.0.0.0:0,tls,x509verify=/etc/pki/libvirt

12 Managing Storage

  • Filename: libvirt_storage.xml
  • ID: cha.libvirt.storage

When managing a VM Guest on the VM Host Server itself, you can access the complete file system of the VM Host Server to attach or create virtual hard disks or to attach existing images to the VM Guest. However, this is not possible when managing VM Guests from a remote host. For this reason, libvirt supports so called Storage Pools, which can be accessed from remote machines.

Tip
Tip: CD/DVD ISO images

To be able to access CD/DVD ISO images on the VM Host Server from remote, they also need to be placed in a storage pool.

libvirt knows two different types of storage: volumes and pools.

Storage Volume

A storage volume is a storage device that can be assigned to a guest—a virtual disk or a CD/DVD/floppy image. Physically (on the VM Host Server) it can be a block device (a partition, a logical volume, etc.) or a file.

Storage Pool

A storage pool is a storage resource on the VM Host Server that can be used for storing volumes, similar to network storage for a desktop machine. Physically it can be one of the following types:

File System Directory (dir)

A directory for hosting image files. The files can be either one of the supported disk formats (raw, qcow2, or qed), or ISO images.

Physical Disk Device (disk)

Use a complete physical disk as storage. A partition is created for each volume that is added to the pool.

Pre-Formatted Block Device (fs)

Specify a partition to be used in the same way as a file system directory pool (a directory for hosting image files). The only difference to using a file system directory is that libvirt takes care of mounting the device.

iSCSI Target (iscsi)

Set up a pool on an iSCSI target. You need to have been logged in to the volume once before, to use it with libvirt. Use the YaST iSCSI Initiator to detect and log in to a volume, see Storage Administration Guide for details. Volume creation on iSCSI pools is not supported, instead each existing Logical Unit Number (LUN) represents a volume. Each volume/LUN also needs a valid (empty) partition table or disk label before you can use it. If missing, use fdisk to add it:

~ # fdisk -cu /dev/disk/by-path/ip-192.168.2.100:3260-iscsi-iqn.2010-10.com.example:[...]-lun-2
Device contains neither a valid DOS partition table, nor Sun, SGI
or OSF disklabel
Building a new DOS disklabel with disk identifier 0xc15cdc4e.
Changes will remain in memory only, until you decide to write them.
After that, of course, the previous content won't be recoverable.

Warning: invalid flag 0x0000 of partition table 4 will be corrected by w(rite)

Command (m for help): w
The partition table has been altered!

Calling ioctl() to re-read partition table.
Syncing disks.
LVM Volume Group (logical)

Use an LVM volume group as a pool. You may either use a predefined volume group, or create a group by specifying the devices to use. Storage volumes are created as partitions on the volume.

Warning
Warning: Deleting the LVM-Based Pool

When the LVM-based pool is deleted in the Storage Manager, the volume group is deleted as well. This results in a non-recoverable loss of all data stored on the pool!

Multipath Devices (mpath)

At the moment, multipathing support is limited to assigning existing devices to the guests. Volume creation or configuring multipathing from within libvirt is not supported.

Network Exported Directory (netfs)

Specify a network directory to be used in the same way as a file system directory pool (a directory for hosting image files). The only difference to using a file system directory is that libvirt takes care of mounting the directory. Supported protocols are NFS and GlusterFS.

SCSI Host Adapter (scsi)

Use an SCSI host adapter in almost the same way as an iSCSI target. We recommend to use a device name from /dev/disk/by-* rather than /dev/sdX. The latter can change (for example, when adding or removing hard disks). Volume creation on iSCSI pools is not supported. Instead, each existing LUN (Logical Unit Number) represents a volume.

Warning
Warning: Security Considerations

To avoid data loss or data corruption, do not attempt to use resources such as LVM volume groups, iSCSI targets, etc., that are also used to build storage pools on the VM Host Server. There is no need to connect to these resources from the VM Host Server or to mount them on the VM Host Server—libvirt takes care of this.

Do not mount partitions on the VM Host Server by label. Under certain circumstances it is possible that a partition is labeled from within a VM Guest with a name already existing on the VM Host Server.

12.1 Managing Storage with Virtual Machine Manager

The Virtual Machine Manager provides a graphical interface—the Storage Manager—to manage storage volumes and pools. To access it, either right-click a connection and choose Details, or highlight a connection and choose Edit › Connection Details. Select the Storage tab.

12.1.1 Adding a Storage Pool

To add a storage pool, proceed as follows:

  1. Click Add in the bottom left corner. The dialog Add a New Storage Pool appears.

  2. Provide a Name for the pool (consisting of alphanumeric characters and _-.) and select a Type. Proceed with Forward.

  3. Specify the required details in the following window. The data that needs to be entered depends on the type of pool you are creating:

    Typedir
    • Target Path: Specify an existing directory.

    Typedisk
    • Target Path: The directory that hosts the devices. The default value /dev should usually fit.

    • Format: Format of the device's partition table. Using auto should usually work. If not, get the required format by running the command parted -l on the VM Host Server.

    • Source Path: Path to the device. It is recommended to use a device name from /dev/disk/by-* rather than the simple /dev/sdX, since the latter can change (for example, when adding or removing hard disks). You need to specify the path that resembles the whole disk, not a partition on the disk (if existing).

    • Build Pool: Activating this option formats the device. Use with care—all data on the device will be lost!

    Typefs
    • Target Path: Mount point on the VM Host Server file system.

    • Format: File system format of the device. The default value auto should work.

    • Source Path: Path to the device file. It is recommended to use a device name from /dev/disk/by-* rather than /dev/sdX, because the latter can change (for example, when adding or removing hard disks).

    Typeiscsi

    Get the necessary data by running the following command on the VM Host Server:

    iscsiadm --mode node

    It will return a list of iSCSI volumes with the following format. The elements in bold text are required:

    IP_ADDRESS:PORT,TPGT TARGET_NAME_(IQN)
    • Target Path: The directory containing the device file. Use /dev/disk/by-path (default) or /dev/disk/by-id.

    • Host Name: Host name or IP address of the iSCSI server.

    • Source Path: The iSCSI target name (IQN).

    Typelogical
    • Target Path: In case you use an existing volume group, specify the existing device path. When building a new LVM volume group, specify a device name in the /dev directory that does not already exist.

    • Source Path: Leave empty when using an existing volume group. When creating a new one, specify its devices here.

    • Build Pool: Only activate when creating a new volume group.

    Typempath
    • Target Path: Support for multipathing is currently limited to making all multipath devices available. Therefore, specify an arbitrary string here that will then be ignored. The path is required, otherwise the XML parser will fail.

    Typenetfs
    • Target Path: Mount point on the VM Host Server file system.

    • Host Name: IP address or host name of the server exporting the network file system.

    • Source Path: Directory on the server that is being exported.

    Typescsi
    • Target Path: The directory containing the device file. Use /dev/disk/by-path (default) or /dev/disk/by-id.

    • Source Path: Name of the SCSI adapter.

    Note
    Note: File Browsing

    Using the file browser by clicking Browse is not possible when operating from remote.

  4. Click Finish to add the storage pool.

12.1.2 Managing Storage Pools

Virtual Machine Manager's Storage Manager lets you create or delete volumes in a pool. You may also temporarily deactivate or permanently delete existing storage pools. Changing the basic configuration of a pool is currently not supported by SUSE.

12.1.2.1 Starting, Stopping and Deleting Pools

The purpose of storage pools is to provide block devices located on the VM Host Server that can be added to a VM Guest when managing it from remote. To make a pool temporarily inaccessible from remote, click Stop in the bottom left corner of the Storage Manager. Stopped pools are marked with State: Inactive and are grayed out in the list pane. By default, a newly created pool will be automatically started On Boot of the VM Host Server.

To start an inactive pool and make it available from remote again, click Start in the bottom left corner of the Storage Manager.

Note
Note: A Pool's State Does not Affect Attached Volumes

Volumes from a pool attached to VM Guests are always available, regardless of the pool's state (Active (stopped) or Inactive (started)). The state of the pool solely affects the ability to attach volumes to a VM Guest via remote management.

To permanently make a pool inaccessible, click Delete in the bottom left corner of the Storage Manager. You may only delete inactive pools. Deleting a pool does not physically erase its contents on VM Host Server—it only deletes the pool configuration. However, you need to be extra careful when deleting pools, especially when deleting LVM volume group-based tools:

Warning
Warning: Deleting Storage Pools

Deleting storage pools based on local file system directories, local partitions or disks has no effect on the availability of volumes from these pools currently attached to VM Guests.

Volumes located in pools of type iSCSI, SCSI, LVM group or Network Exported Directory will become inaccessible from the VM Guest if the pool is deleted. Although the volumes themselves will not be deleted, the VM Host Server will no longer have access to the resources.

Volumes on iSCSI/SCSI targets or Network Exported Directory will become accessible again when creating an adequate new pool or when mounting/accessing these resources directly from the host system.

When deleting an LVM group-based storage pool, the LVM group definition will be erased and the LVM group will no longer exist on the host system. The configuration is not recoverable and all volumes from this pool are lost.

12.1.2.2 Adding Volumes to a Storage Pool

Virtual Machine Manager lets you create volumes in all storage pools, except in pools of types Multipath, iSCSI, or SCSI. A volume in these pools is equivalent to a LUN and cannot be changed from within libvirt.

  1. A new volume can either be created using the Storage Manager or while adding a new storage device to a VM Guest. In either case, select a storage pool from the left panel, then click Create new volume.

  2. Specify a Name for the image and choose an image format.

    Note that SUSE currently only supports raw, qcow2, or qed images. The latter option is not available on LVM group-based pools.

    Next to Max Capacity, specify the amount maximum size that the disk image is allowed to reach. Unless you are working with a qcow2 image, you can also set an amount for Allocation that should be allocated initially. If both values differ, a sparse image file will be created which grows on demand.

    For qcow2 images, you can use a Backing Store (also called backing file) which constitutes a base image. The newly created qcow2 image will then only record the changes that are made to the base image.

  3. Start the volume creation by clicking Finish.

12.1.2.3 Deleting Volumes From a Storage Pool

Deleting a volume can only be done from the Storage Manager, by selecting a volume and clicking Delete Volume. Confirm with Yes.

Warning
Warning: Volumes Can Be Deleted Even While in Use

Volumes can be deleted even if they are currently used in an active or inactive VM Guest. There is no way to recover a deleted volume.

Whether a volume is used by a VM Guest is indicated in the Used By column in the Storage Manager.

12.2 Managing Storage with virsh

Managing storage from the command line is also possible by using virsh. However, creating storage pools is currently not supported by SUSE. Therefore, this section is restricted to documenting functions like starting, stopping and deleting pools and volume management.

A list of all virsh subcommands for managing pools and volumes is available by running virsh help pool and virsh help volume, respectively.

12.2.1 Listing Pools and Volumes

List all pools currently active by executing the following command. To also list inactive pools, add the option --all:

virsh pool-list --details

Details about a specific pool can be obtained with the pool-info subcommand:

virsh pool-info POOL

Volumes can only be listed per pool by default. To list all volumes from a pool, enter the following command.

virsh vol-list --details POOL

At the moment virsh offers no tools to show whether a volume is used by a guest or not. The following procedure describes a way to list volumes from all pools that are currently used by a VM Guest.

Procedure 12.1: Listing all Storage Volumes Currently Used on a VM Host Server
  1. Create an XSLT style sheet by saving the following content to a file, for example, ~/libvirt/guest_storage_list.xsl:

    <?xml version="1.0" encoding="UTF-8"?>
    <xsl:stylesheet version="1.0"
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
      <xsl:output method="text"/>
      <xsl:template match="text()"/>
      <xsl:strip-space elements="*"/>
      <xsl:template match="disk">
        <xsl:text>  </xsl:text>
        <xsl:value-of select="(source/@file|source/@dev|source/@dir)[1]"/>
        <xsl:text>&#10;</xsl:text>
      </xsl:template>
    </xsl:stylesheet>
  2. Run the following commands in a shell. It is assumed that the guest's XML definitions are all stored in the default location (/etc/libvirt/qemu). xsltproc is provided by the package libxslt.

    SSHEET="$HOME/libvirt/guest_storage_list.xsl"
    cd /etc/libvirt/qemu
    for FILE in *.xml; do
      basename $FILE .xml
      xsltproc $SSHEET $FILE
    done

12.2.2 Starting, Stopping and Deleting Pools

Use the virsh pool subcommands to start, stop or delete a pool. Replace POOL with the pool's name or its UUID in the following examples:

Stopping a Pool
virsh pool-destroy POOL
Note
Note: A Pool's State Does not Affect Attached Volumes

Volumes from a pool attached to VM Guests are always available, regardless of the pool's state (Active (stopped) or Inactive (started)). The state of the pool solely affects the ability to attach volumes to a VM Guest via remote management.

Deleting a Pool
virsh pool-delete POOL
Warning
Warning: Deleting Storage Pools

See Warning: Deleting Storage Pools

Starting a Pool
virsh pool-start POOL
Enable Autostarting a Pool
virsh pool-autostart POOL

Only pools that are marked to autostart will automatically be started if the VM Host Server reboots.

Disable Autostarting a Pool
virsh pool-autostart POOL --disable

12.2.3 Adding Volumes to a Storage Pool

virsh offers two ways to add volumes to storage pools: either from an XML definition with vol-create and vol-create-from or via command line arguments with vol-create-as. The first two methods are currently not supported by SUSE, therefore this section focuses on the subcommand vol-create-as.

To add a volume to an existing pool, enter the following command:

virsh vol-create-as POOL1NAME2 12G --format3raw|qcow2|qed4 --allocation 4G5

1

Name of the pool to which the volume should be added

2

Name of the volume

3

Size of the image, in this example 12 gigabytes. Use the suffixes k, M, G, T for kilobyte, megabyte, gigabyte, and terabyte, respectively.

4

Format of the volume. SUSE currently supports raw, qcow2, and qed.

5

Optional parameter. By default virsh creates a sparse image file that grows on demand. Specify the amount of space that should be allocated with this parameter (4 gigabytes in this example). Use the suffixes k, M, G, T for kilobyte, megabyte, gigabyte, and terabyte, respectively.

When not specifying this parameter, a sparse image file with no allocation will be generated. To create a non-sparse volume, specify the whole image size with this parameter (would be 12G in this example).

12.2.3.1 Cloning Existing Volumes

Another way to add volumes to a pool is to clone an existing volume. The new instance is always created in the same pool as the original.

virsh vol-clone NAME_EXISTING_VOLUME1NAME_NEW_VOLUME2 --pool POOL3

1

Name of the existing volume that should be cloned

2

Name of the new volume

3

Optional parameter. libvirt tries to locate the existing volume automatically. If that fails, specify this parameter.

12.2.4 Deleting Volumes from a Storage Pool

To permanently delete a volume from a pool, use the subcommand vol-delete:

virsh vol-delete NAME --pool POOL

--pool is optional. libvirt tries to locate the volume automatically. If that fails, specify this parameter.

Warning
Warning: No Checks Upon Volume Deletion

A volume will be deleted in any case, regardless of whether it is currently used in an active or inactive VM Guest. There is no way to recover a deleted volume.

Whether a volume is used by a VM Guest can only be detected by using by the method described in Procedure 12.1, “Listing all Storage Volumes Currently Used on a VM Host Server”.

12.2.5 Attaching Volumes to a VM Guest

After you create a volume as described in Section 12.2.3, “Adding Volumes to a Storage Pool”, you can attach it to a virtual machine and use it as a hard disk:

virsh attach-disk DOMAIN SOURCE_IMAGE_FILE TARGET_DISK_DEVICE

For example:

virsh attach-disk sles12sp3 /virt/images/example_disk.qcow2 sda2

To check if the new disk is attached, inspect the result of the virsh dumpxml command:

root # virsh dumpxml sles12sp3
[...]
<disk type='file' device='disk'>
 <driver name='qemu' type='raw'/>
 <source file='/virt/images/example_disk.qcow2'/>
 <backingStore/>
 <target dev='sda2' bus='scsi'/>
 <alias name='scsi0-0-0'/>
 <address type='drive' controller='0' bus='0' target='0' unit='0'/>
</disk>
[...]

12.2.5.1 Hotplug or Persistent Change

You can attach disks to both active and inactive domains. The attachment is controlled by the --live and --config options:

--live

Hotplugs the disk to an active domain. The attachment is not saved in the domain configuration. Using --live on an inactive domain is an error.

--config

Changes the domain configuration persistently. The attached disk is then available after the next domain start.

--live--config

Hotplugs the disk and adds it to the persistent domain configuration.

Tip
Tip: virsh attach-device

virsh attach-device is the more generic form of virsh attach-disk. You can use it to attach other types of devices to a domain.

12.2.6 Detaching Volumes from a VM Guest

To detach a disk from a domain, use virsh detach-disk:

root # virsh detach-disk DOMAIN TARGET_DISK_DEVICE

For example:

root # virsh detach-disk sles12sp3 sda2

You can control the attachment with the --live and --config options as described in Section 12.2.5, “Attaching Volumes to a VM Guest”.

12.3 Locking Disk Files and Block Devices with virtlockd

Locking block devices and disk files prevents concurrent writes to these resources from different VM Guests. It provides protection against starting the same VM Guest twice, or adding the same disk to two different virtual machines. This will reduce the risk of a virtual machine's disk image becoming corrupted because of a wrong configuration.

The locking is controlled by a daemon called virtlockd. Since it operates independently from the libvirtd daemon, locks will endure a crash or a restart of libvirtd. Locks will even persist in the case of an update of the virtlockd itself, since it can re-execute itself. This ensures that VM Guests do not need to be restarted upon a virtlockd update. virtlockd is supported for KVM, QEMU, and Xen.

12.3.1 Enable Locking

Locking virtual disks is not enabled by default on SUSE Linux Enterprise Server. To enable and automatically start it upon rebooting, perform the following steps:

  1. Edit /etc/libvirt/qemu.conf and set

    lock_manager = "lockd"
  2. Start the virtlockd daemon with the following command:

    systemctl start virtlockd
  3. Restart the libvirtd daemon with:

    systemctl restart libvirtd
  4. Make sure virtlockd is automatically started when booting the system:

    systemctl enable virtlockd

12.3.2 Configure Locking

By default virtlockd is configured to automatically lock all disks configured for your VM Guests. The default setting uses a "direct" lockspace, where the locks are acquired against the actual file paths associated with the VM Guest <disk> devices. For example, flock(2) will be called directly on /var/lib/libvirt/images/my-server/disk0.raw when the VM Guest contains the following <disk> device:

<disk type='file' device='disk'>
 <driver name='qemu' type='raw'/>
 <source file='/var/lib/libvirt/images/my-server/disk0.raw'/>
 <target dev='vda' bus='virtio'/>
</disk>

The virtlockd configuration can be changed by editing the file /etc/libvirt/qemu-lockd.conf. It also contains detailed comments with further information. Make sure to activate configuration changes by reloading virtlockd:

systemctl reload virtlockd
Note
Note: Locking Currently Only Available for All Disks

Currently, locking can only be activated globally, so that all virtual disks are locked. Support for locking selected disks is planned for future releases.

12.3.2.1 Enabling an Indirect Lockspace

The default configuration of virtlockd uses a direct lockspace. This means that the locks are acquired against the actual file paths associated with the <disk> devices.

If the disk file paths are not accessible to all hosts, virtlockd can be configured to allow an indirect lockspace. This means that a hash of the disk file path is used to create a file in the indirect lockspace directory. The locks are then held on these hash files instead of the actual disk file paths. Indirect lockspace is also useful if the file system containing the disk files does not support fcntl() locks. An indirect lockspace is specified with the file_lockspace_dir setting:

file_lockspace_dir = "/MY_LOCKSPACE_DIRECTORY"

12.3.2.2 Enable Locking on LVM or iSCSI Volumes

When wanting to lock virtual disks placed on LVM or iSCSI volumes shared by several hosts, locking needs to be done by UUID rather than by path (which is used by default). Furthermore, the lockspace directory needs to be placed on a shared file system accessible by all hosts sharing the volume. Set the following options for LVM and/or iSCSI:

lvm_lockspace_dir = "/MY_LOCKSPACE_DIRECTORY"
iscsi_lockspace_dir = "/MY_LOCKSPACE_DIRECTORY"

12.4 Online Resizing of Guest Block Devices

Sometimes you need to change—extend or shrink—the size of the block device used by your guest system. For example, when the disk space originally allocated is no longer enough, it is time to increase its size. If the guest disk resides on a logical volume, you can resize it while the guest system is running. This is a big advantage over an offline disk resizing (see the virt-resize command from the Section 17.3, “Guestfs Tools” package) as the service provided by the guest is not interrupted by the resizing process. To resize a VM Guest disk, follow these steps:

Procedure 12.2: Online Resizing of Guest Disk
  1. Inside the guest system, check the current size of the disk (for example /dev/vda).

    root # fdisk -l /dev/vda
    Disk /dev/sda: 160.0 GB, 160041885696 bytes, 312581808 sectors
    Units = sectors of 1 * 512 = 512 bytes
    Sector size (logical/physical): 512 bytes / 512 bytes
    I/O size (minimum/optimal): 512 bytes / 512 bytes
  2. On the host, resize the logical volume holding the /dev/vda disk of the guest to the required size, for example 200 GB.

    root # lvresize -L 2048M /dev/mapper/vg00-home
    Extending logical volume home to 2.00 GiB
    Logical volume home successfully resized
  3. On the host, resize the block device related to the disk /dev/mapper/vg00-home of the guest. Note that you can find the DOMAIN_ID with virsh list.

    root # virsh blockresize  --path /dev/vg00/home --size 2048M DOMAIN_ID
    Block device '/dev/vg00/home' is resized
  4. Check that the new disk size is accepted by the guest.

    root # fdisk -l /dev/vda
    Disk /dev/sda: 200.0 GB, 200052357120 bytes, 390727260 sectors
    Units = sectors of 1 * 512 = 512 bytes
    Sector size (logical/physical): 512 bytes / 512 bytes
    I/O size (minimum/optimal): 512 bytes / 512 bytes

12.5 Sharing Directories between Host and Guests (File System Pass-Through)

libvirt allows to share directories between host and guests using QEMU's file system pass-through (also called VirtFS) feature. Such a directory can be also be accessed by several VM Guests at once and therefore be used to exchange files between VM Guests.

Note
Note: Windows Guests and File System Pass-Through

Note that sharing directories between VM Host Server and Windows guests via File System Pass-Through does not work, because Windows lacks the drivers required to mount the shared directory.

To make a shared directory available on a VM Guest, proceed as follows:

  1. Open the guest's console in Virtual Machine Manager and either choose View › Details from the menu or click Show virtual hardware details in the toolbar. Choose Add Hardware › Filesystem to open the Filesystem Passthrough dialog.

  2. Driver allows you to choose between a Handle or Path base driver. The default setting is Path. Mode lets you choose the security model, which influences the way file permissions are set on the host. Three options are available:

    Passthrough (Default)

    Files on the file system are directly created with the client-user's credentials. This is very similar to what NFSv3 is using.

    Squash

    Same as Passthrough, but failure of privileged operations like chown are ignored. This is required when KVM is not run with root privileges.

    Mapped

    Files are created with the file server's credentials (qemu.qemu). The user credentials and the client-user's credentials are saved in extended attributes. This model is recommended when host and guest domains should be kept completely isolated.

  3. Specify the path to the directory on the VM Host Server with Source Path. Enter a string at Target Path that will be used as a tag to mount the shared directory. Note that the string of this field is a tag only, not a path on the VM Guest.

  4. Apply the setting. If the VM Guest is currently running, you need to shut it down to apply the new setting (rebooting the guest is not sufficient).

  5. Boot the VM Guest. To mount the shared directory, enter the following command:

    sudo mount -t 9p -o trans=virtio,version=9p2000.L,rw TAG /MOUNT_POINT

    To make the shared directory permanently available, add the following line to the /etc/fstab file:

    TAG   /MOUNT_POINT    9p  trans=virtio,version=9p2000.L,rw    0   0

12.6 Using RADOS Block Devices with libvirt

RADOS Block Devices (RBD) store data in a Ceph cluster. They allow snapshotting, replication, and data consistency. You can use an RBD from your libvirt-managed VM Guests similarly you use other block devices.

Refer to SUSE Enterprise Storage documentation for more details.

13 Managing Networks

  • Filename: libvirt_networking.xml
  • ID: cha.libvirt.networks
Abstract

This chapter introduces common networking configurations supported by libvirt. It does not depend on the hypervisor used. It is valid for all hypervisors supported by libvirt, such as KVM or Xen. These setups can be achieved using both the graphical interface of Virtual Machine Manager and the command line tool virsh.

There are two common network setups to provide a VM Guest with a network connection:

  • A virtual network for the guest

  • A network bridge over a host's physical network interface that the guest can use

13.1 Virtual Networks

A virtual network is a computer network which does not consist of a physical network link, but rather uses a virtual network link. Each host can have several virtual networks defined. Virtual networks are based on virtual devices that connect virtual machines inside a hypervisor. They allow outgoing traffic translated to the LAN and are provided with DHCP and DNS services. Virtual networks can be either isolated, or forwarded to a physical network.

Guests inside an isolated virtual network can communicate with each other, but cannot communicate with guests outside the virtual network. Also, guests not belonging to the isolated virtual network cannot communicate with guests inside.

On the other hand, guests inside a forwarded (NAT, network address translation) virtual network can make any outgoing network connection they request. Incoming connections are allowed from VM Host Server, and from other guests connected to the same virtual network. All other incoming connections are blocked by iptables rules.

A standard libvirt installation on SUSE Linux Enterprise Server already comes with a predefined virtual network providing DHCP server and network address translation (NAT) named "default".

13.1.1 Managing Virtual Networks with Virtual Machine Manager

You can define, configure, and operate both isolated and forwarded virtual networks with Virtual Machine Manager.

13.1.1.1 Defining Virtual Networks

  1. Start Virtual Machine Manager. In the list of available connections, right-click the name of the connection for which you need to configure the virtual network, and then select Details.

  2. In the Connection Details window, click the Virtual Networks tab. You can see the list of all virtual networks available for the current connection. On the right, there are details of the selected virtual network.

    Connection Details
    Figure 13.1: Connection Details
  3. To add a new virtual network, click Add.

  4. Specify a name for the new virtual network and click Forward.

    Create virtual network
    Figure 13.2: Create virtual network
  5. To specify an IPv4 network address space definition, activate the relevant option and type it into the Network text entry.

    Create virtual network
    Figure 13.3: Create virtual network
  6. libvirt can provide your virtual network with a DHCP server. If you need it, activate Enable DHCPv4, then type the start and end IP address range of assignable addresses.

  7. To enable static routing for the new virtual network, activate the relevant option and type the network and gateway addresses.

  8. Click Forward to proceed.

  9. To specify IPv6-related options—network address space, DHCPv6 server, or static route—activate Enable IPv6 network address space definition and activate the relevant options and fill in the relevant boxes.

  10. Click Forward to proceed.

  11. Select whether you want isolated or forwarded virtual network.

    Create virtual network
    Figure 13.4: Create virtual network

    For forwarded networks, specify the network interface to which the requests will be forwarded, and one of the forwarding modes: While NAT (network address translation) remaps the virtual network address space and allows sharing a single IP address, Routed connects the virtual switch to the physical host LAN with no network translation.

  12. If you did not specify IPv6 network address space definition earlier, you can enable IPv6 internal routing between virtual machines.

  13. (Optional) Optionally, change the DNS domain name.

  14. Click Finish to create the new virtual network. On the VM Host Server, a new virtual network bridge virbrX is available, which corresponds to the newly created virtual network. You can check with brctl show. libvirt automatically adds iptables rules to allow traffic to/from guests attached to the new virbrX device.

13.1.1.2 Starting Virtual Networks

To start a virtual network that is temporarily stopped, follow these steps:

  1. Start Virtual Machine Manager. In the list of available connections, right-click the name of the connection for which you need to configure the virtual network, and then select Details.

  2. In the Connection Details window, click the Virtual Networks tab. You can see the list of all virtual networks available for the current connection.

  3. To start the virtual network, click Start.

13.1.1.3 Stopping Virtual Networks

To stop an active virtual network, follow these steps:

  1. Start Virtual Machine Manager. In the list of available connections, right-click the name of the connection for which you need to configure the virtual network, and then select Details.

  2. In the Connection Details window, click the Virtual Networks tab. You can see the list of all virtual networks available for the current connection.

  3. Select the virtual network to be stopped, then click Stop.

13.1.1.4 Deleting Virtual Networks

To delete a virtual network from VM Host Server, follow these steps:

  1. Start Virtual Machine Manager. In the list of available connections, right-click the name of the connection for which you need to configure the virtual network, and then select Details.

  2. In the Connection Details window, click the Virtual Networks tab. You can see the list of all virtual networks available for the current connection.

  3. Select the virtual network to be deleted, then click Delete.

13.1.1.5 Obtaining IP Addresses with nsswitch for NAT Networks (in KVM)

  • On VM Host Server, install libvirt-nss, which provides NSS support for libvirt:

    zypper in libvirt-nss
  • Add libvirt to /etc/nsswitch.conf:

    ...
    hosts:  files libvirt mdns_minimal [NOTFOUND=return] dns
    ...
  • If NSCD is running, restart it:

    systemctl restart nscd

Now you can reach the guest system by name from the host.

The NSS module has limited functionality. It reads /var/lib/libvirt/dnsmasq/*.status files to find the host name and corresponding IP addresses in a JSON record describing each lease provided by dnsmasq. Host name translation can only be done on those VM Host Servers using a libvirt-managed bridged network backed by dnsmasq.

For more information, see http://wiki.libvirt.org/page/NSS_module.

13.1.2 Managing Virtual Networks with virsh

You can manage libvirt-provided virtual networks with the virsh command line tool. To view all network related virsh commands, run

# virsh help network
Networking (help keyword 'network'):
 net-autostart                  autostart a network
        net-create                     create a network from an XML file
        net-define                     define (but don't start) a network from an XML file
        net-destroy                    destroy (stop) a network
        net-dumpxml                    network information in XML
        net-edit                       edit XML configuration for a network
        net-event                      Network Events
        net-info                       network information
        net-list                       list networks
        net-name                       convert a network UUID to network name
        net-start                      start a (previously defined) inactive network
        net-undefine                   undefine an inactive network
        net-update                     update parts of an existing network's configuration
 net-uuid                       convert a network name to network UUID

To view brief help information for a specific virsh command, run virsh help VIRSH_COMMAND:

# virsh help net-create
  NAME
    net-create - create a network from an XML file

  SYNOPSIS
    net-create <file>

  DESCRIPTION
    Create a network.

  OPTIONS
    [--file] <string>  file containing an XML network description

13.1.2.1 Creating a Network

To create a new running virtual network, run

root # virsh net-create VNET_DEFINITION.xml

The VNET_DEFINITION.xml XML file includes the definition of the virtual network that libvirt accepts.

To define a new virtual network without activating it, run

root # virsh net-define VNET_DEFINITION.xml

The following examples illustrate definitions of different types of virtual networks.

Example 13.1: NAT Based Network

The following configuration allows VM Guests outgoing connectivity if it is available on VM Host Server. In the absence of VM Host Server networking, it allows guests to talk directly to each other.

<network>
<name>vnet_nated</name>1
<bridge name="virbr1" />2
 <forward mode="nat"/>3
 <ip address="192.168.122.1" netmask="255.255.255.0">4
  <dhcp>
   <range start="192.168.122.2" end="192.168.122.254" />5
   <host mac="52:54:00:c7:92:da" name="host1.testing.com" \
    ip="192.168.1.23.101" />6
   <host mac="52:54:00:c7:92:db" name="host2.testing.com" \
    ip="192.168.1.23.102" />
   <host mac="52:54:00:c7:92:dc" name="host3.testing.com" \
    ip="192.168.1.23.103" />
  </dhcp>
 </ip>
</network>

1

The name of the new virtual network.

2

The name of the bridge device used to construct the virtual network. When defining a new network with a <forward> mode of "nat" or "route" (or an isolated network with no <forward> element), libvirt will automatically generate a unique name for the bridge device if none is given.

3

Inclusion of the <forward> element indicates that the virtual network will be connected to the physical LAN. The mode attribute specifies the forwarding method. The most common modes are "nat" (default, network address translation), "route" (direct forwarding to the physical network, no address translation), and "bridge" (network bridge configured outside of libvirt). If the <forward> element is not specified, the virtual network will be isolated from other networks. For a complete list of forwarding modes, see http://libvirt.org/formatnetwork.html#elementsConnect.

4

The IP address and netmask for the network bridge.

5

Enable DHCP server for the virtual network, offering IP addresses ranging from the specified start and end attribute.

6

The optional <host> elements specify hosts that will be given names and predefined IP addresses by the built-in DHCP server. Any IPv4 host element must specify the following: the MAC address of the host to be assigned a given name, the IP to be assigned to that host, and the name to be given to that host by the DHCP server. An IPv6 host element differs slightly from that for IPv4: there is no mac attribute since a MAC address has no defined meaning in IPv6. Instead, the name attribute is used to identify the host to be assigned the IPv6 address. For DHCPv6, the name is the plain name of the client host sent by the client to the server. Note that this method of assigning a specific IP address can also be used instead of the mac attribute for IPv4.

Example 13.2: Routed Network

The following configuration routes traffic from the virtual network to the LAN without applying any NAT. The IP address range must be preconfigured in the routing tables of the router on the VM Host Server network.

<network>
 <name>vnet_routed</name>
 <bridge name="virbr1" />
 <forward mode="route" dev="eth1"/>1
 <ip address="192.168.122.1" netmask="255.255.255.0">
  <dhcp>
   <range start="192.168.122.2" end="192.168.122.254" />
  </dhcp>
 </ip>
</network>

1

The guest traffic may only go out via the eth1 network device on the VM Host Server.

Example 13.3: Isolated Network

This configuration provides a completely isolated private network. The guests can talk to each other, and to VM Host Server, but cannot reach any other machines on the LAN, as the <forward> element is missing in the XML description.

<network>
 <name>vnet_isolated</name>
 <bridge name="virbr3" />
 <ip address="192.168.152.1" netmask="255.255.255.0">
  <dhcp>
   <range start="192.168.152.2" end="192.168.152.254" />
  </dhcp>
 </ip>
 </network>
Example 13.4: Using an Existing Bridge on VM Host Server

This configuration shows how to use an existing VM Host Server's network bridge br0. VM Guests are directly connected to the physical network. Their IP addresses will all be on the subnet of the physical network, and there will be no restrictions on incoming or outgoing connections.

<network>
        <name>host-bridge</name>
        <forward mode="bridge"/>
        <bridge name="br0"/>
</network>

13.1.2.2 Listing Networks

To list all virtual networks available to libvirt, run:

root # virsh net-list --all

 Name                 State      Autostart     Persistent
----------------------------------------------------------
 crowbar              active     yes           yes
 vnet_nated           active     yes           yes
 vnet_routed          active     yes           yes
 vnet_isolated        inactive   yes           yes

To list available domains, run:

root # virsh list
 Id    Name                           State
----------------------------------------------------
 1     nated_sles12sp1                running
 ...

To get a list of interfaces of a running domain, run domifaddr DOMAIN, or optionally specify the interface to limit the output to this interface. By default, it additionally outputs their IP and MAC addresses:

root # virsh domifaddr nated_sles12sp1 --interface vnet0 --source lease
 Name       MAC address          Protocol     Address
-------------------------------------------------------------------------------
 vnet0      52:54:00:9e:0d:2b    ipv6         fd00:dead:beef:55::140/64
 -          -                    ipv4         192.168.100.168/24

To print brief information of all virtual interfaces associated with the specified domain, run:

root # virsh domiflist nated_sles12sp1
Interface  Type       Source       Model       MAC
---------------------------------------------------------
vnet0      network    vnet_nated   virtio      52:54:00:9e:0d:2b

13.1.2.3 Getting Details about a Network

To get detailed information about a network, run:

root # virsh net-info vnet_routed
Name:           vnet_routed
UUID:           756b48ff-d0c6-4c0a-804c-86c4c832a498
Active:         yes
Persistent:     yes
Autostart:      yes
Bridge:         virbr5

13.1.2.4 Starting a Network

To start an inactive network that was already defined, find its name (or unique identifier, UUID) with:

root # virsh net-list --inactive
 Name                 State      Autostart     Persistent
----------------------------------------------------------
 vnet_isolated        inactive   yes           yes

Then run:

root # virsh net-start vnet_isolated
Network vnet_isolated started

13.1.2.5 Stopping a Network

To stop an active network, find its name (or unique identifier, UUID) with:

root # virsh net-list --inactive
 Name                 State      Autostart     Persistent
----------------------------------------------------------
 vnet_isolated        active     yes           yes

Then run:

root # virsh net-destroy vnet_isolated
Network vnet_isolated destroyed

13.1.2.6 Removing a Network

To remove the definition of an inactive network from VM Host Server permanently, run:

root # virsh net-undefine vnet_isolated
Network vnet_isolated has been undefined

13.2 Bridged Networking

A network bridge is used to connect two or more network segments. It behaves like a virtual network switch, and guest machines treat it transparently as a physical network interface. Any physical or virtual device can be connected to the bridge.

If there is a network bridge present on VM Host Server, you can connect a VM Guest to it directly. This provides the VM Guest with full incoming and outgoing network access.

13.2.1 Managing Network Bridges with YaST

This section includes procedures to add or remove network bridges with YaST.

13.2.1.1 Adding a Network Bridge

To add a network bridge on VM Host Server, follow these steps:

  1. Start YaST › System › Network Settings.

  2. Activate the Overview tab and click Add.

  3. Select Bridge from the Device Type list and enter the bridge device interface name in the Configuration Name entry. Proceed with Next.

  4. In the Address tab, specify networking details such as DHCP/static IP address, subnet mask or host name.

    Using Dynamic Address is only useful when also assigning a device to a bridge that is connected to some DHCP server.

    If you intend to create a virtual bridge that has no connection to a real Ethernet device, use Statically assigned IP Address. In this case, it is a good idea to use addresses from the private IP address ranges, for example, 192.168.x.x or 10.x.x.x.

    To create a bridge that should only serve as a connection between the different guests without connection to the host system, set the IP address to 0.0.0.0 and the subnet mask to 255.255.255.255. The network scripts handle this special address as an unset IP address.

  5. Activate the Bridged Devices tab and activate the network devices you want to include in the network bridge.

  6. Click Next to return to the Overview tab and confirm with OK. The new network bridge should be active on VM Host Server now.

13.2.1.2 Deleting a Network Bridge

To delete an existing network bridge, follow these steps:

  1. Start YaST › System › Network Settings.

  2. Select the bridge device you want to delete from the list in the Overview tab.

  3. Delete the bridge with Delete and confirm with OK.

13.2.2 Managing Network Bridges with brctl

This section includes procedures to add or remove network bridges with the brctl command line tool.

13.2.2.1 Adding a Network Bridge

To add a new network bridge device on VM Host Server with brctl, follow these steps:

  1. Log in as root on the VM Host Server where you want to create a new network bridge.

  2. Choose a name for the new bridge—VIRBR_TEST in our example— and run

    root # brctl addbr VIRBR_TEST
  3. Check if the bridge was created on VM Host Server:

    root # brctl show
    bridge name     bridge id           STP enabled     interfaces
    br0             8000.e06995ec09e8   no              eth0
    virbr0          8000.525400b37ec9   yes             virbr0-nic
    virbr_test      8000.000000000000   no

    virbr_test is present, but is not associated with any physical network interface.

  4. Add a network interface to the bridge:

    root # brctl addif eth1
    Important
    Important: Network Interface Must Be Unused

    You can only enslave a network interface that is not yet used by other network bridge.

  5. Optionally, enable STP (see Spanning Tree Protocol):

    root # brctl stp VIRBR_TEST on

13.2.2.2 Deleting a Network Bridge

To delete an existing network bridge device on VM Host Server with brctl, follow these steps:

  1. Log in as root on the VM Host Server where you want to delete an existing network bridge.

  2. List existing network bridges to identify the name of the bridge to remove:

    root # brctl show
    bridge name     bridge id           STP enabled     interfaces
    br0             8000.e06995ec09e8   no              eth0
    virbr0          8000.525400b37ec9   yes             virbr0-nic
    virbr_test      8000.000000000000   yes             eth1
  3. Delete the bridge:

    root # brctl delbr VIRBR_TEST

13.2.3 Using VLAN Interfaces

Sometimes, it is necessary to create a private connection either between two VM Host Servers or between VM Guest systems. For example, to migrate VM Guest to hosts in a different network segment, or to create a private bridge that only VM Guest systems may connect to (even when running on different VM Host Server systems). An easy way to build such connections is to set up VLAN networks.

VLAN interfaces are commonly set up on the VM Host Server. They either interconnect the different VM Host Server systems, or they may be set up as a physical interface to an otherwise virtual-only bridge. It is even possible to create a bridge with a VLAN as a physical interface that has no IP address in the VM Host Server. That way, the guest systems have no possibility to access the host over this network.

Run the YaST module System › Network Settings. Follow this procedure to set up the VLAN device:

Procedure 13.1: Setting up VLAN Interfaces with YaST
  1. Click Add to create a new network interface.

  2. In the Hardware Dialog, select Device Type VLAN.

  3. Change the value of Configuration Name to the ID of your VLAN. Note that VLAN ID 1 is commonly used for management purposes.

  4. Click Next.

  5. Select the interface that the VLAN device should connect to below Real Interface for VLAN. If the desired interface does not appear in the list, first set up this interface without an IP Address.

  6. Select the desired method for assigning an IP address to the VLAN device.

  7. Click Next to finish the configuration.

It is also possible to use the VLAN interface as a physical interface of a bridge. This makes it possible to connect several VM Host Server-only networks and allows to live-migrate VM Guest systems that are connected to such a network.

YaST does not always allow to set no IP address. However, this may be a desired feature especially if VM Host Server-only networks should be connected. In this case, use the special address 0.0.0.0 with netmask 255.255.255.255. The system scripts handle this address as no IP address set.

14 Configuring Virtual Machines

  • Filename: libvirt_configuration.xml
  • ID: cha.libvirt.config
Abstract

Virtual Machine Manager's Details view offers in-depth information about the VM Guest's complete configuration and hardware equipment. Using this view, you can also change the guest configuration or add and modify virtual hardware. To access this view, open the guest's console in Virtual Machine Manager and either choose View › Details from the menu, or click Show virtual hardware details in the toolbar.

Details View of a VM Guest
Figure 14.1: Details View of a VM Guest

The left panel of the window lists VM Guest overview and already installed hardware. After clicking an item in the list, you can access its detailed settings in the details view. You can change the hardware parameters to match your needs, then click Apply to confirm them. Some changes take effect immediately, while others need a reboot of the machine—and virt-manager warns you about that fact.

To remove installed hardware from a VM Guest, select the appropriate list entry in the left panel and then click Remove in the bottom right of the window.

To add new hardware, click Add Hardware below the left panel, then select the type of the hardware you want to add in the Add New Virtual Hardware window. Modify its parameters and confirm with Finish.

The following sections describe configuration options for the specific hardware type being added. They do not focus on modifying an existing piece of hardware as the options are identical.

14.1 Machine Setup

This section describes the setup of the virtualized processor and memory hardware. These components are vital to a VM Guest, therefore you cannot remove them. It also shows how to view the overview and performance information, and how to change boot options.

14.1.1 Overview

Overview shows basic details about VM Guest and the hypervisor.

Overview details
Figure 14.2: Overview details

Name, Title, and Description are editable and help you identify VM Guest in the Virtual Machine Manager list of machines.

VM Guest Title and Description
Figure 14.3: VM Guest Title and Description

UUID shows the universally unique identifier of the virtual machine, while Status shows its current status—Running, Paused, or Shutoff.

The Hypervisor Details section shows the hypervisor type, CPU architecture, used emulator, and chipset type. None of the hypervisor parameters can be changed.

14.1.2 Performance

Performance shows regularly updated charts of CPU and memory usage, and disk and network I/O.

Performance
Figure 14.4: Performance
Tip
Tip: Enabling Disabled Charts

Not all the charts in the Graph view are enabled by default. To enable these charts, go to File › View Manager, then select Edit › Preferences › Polling, and check the charts that you want to see regularly updated.

Statistics Charts
Figure 14.5: Statistics Charts

14.1.3 Processor

Processor includes detailed information about VM Guest processor configuration.

Processor View
Figure 14.6: Processor View

In the CPUs section, you can configure several parameters related to the number of allocated CPUs.

Logical host CPUs

The real number of CPUs installed on VM Host Server.

Current allocation

The number of currently allocated CPUs. You can hotplug more CPUs by increasing this value up to the Maximum allocation value.

Maximum allocation

Maximum number of allocable CPUs for the current session. Any change to this value will take effect after the next VM Guest reboot.

The Configuration section lets you configure the CPU model and topology.

When activated, the Copy host CPU configuration option uses the host CPU model for VM Guest. Otherwise you need to specify the CPU model from the drop-down box.

After you activate Manually set CPU topology, you can specify a custom number of sockets, cores and threads for the CPU.

14.1.4 Memory

Memory contains information about the memory that is available to VM Guest.

Memory View
Figure 14.7: Memory View
Total host memory

Total amount of memory installed on VM Host Server.

Current allocation

The amount of memory currently available to VM Guest. You can hotplug more memory by increasing this value up to the value of Maximum allocation.

Maximum allocation

The maximum value to which you can hotplug the currently available memory. Any change to this value will take effect after the next VM Guest reboot.

14.1.5 Boot Options

Boot Options introduces options affecting the VM Guest boot process.

Boot Options
Figure 14.8: Boot Options

In the Autostart section, you can specify whether the virtual machine should automatically start during the VM Host Server boot phase.

In the Boot device order, activate the devices that will be used for booting VM Guest. You can change their order with the up and down arrow buttons on the right side of the list. To choose from a list of bootable devices on VM Guest start, activate Enable boot menu.

To boot a different kernel than the one on the boot device, activate Enable direct kernel boot and specify the paths to the alternative kernel and initrd placed on the VM Host Server file system. You can also specify kernel arguments that will be passed to the loaded kernel.

14.2 Storage

This section gives you a detailed description of configuration options for storage devices. It includes both hard disks and removable media, such as USB or CD-ROM drives.

Procedure 14.1: Adding a New Storage Device
  1. Click Add Hardware below the left panel, then select Storage from the Add New Virtual Hardware window.

    Add a New Storage
    Figure 14.9: Add a New Storage
  2. To create a qcow2 disk image in the default location, activate Create a disk image for the virtual machine and specify its size in gigabytes.

    To gain more control over the disk image creation, activate Select or create custom storage and click Manage to manage storage pools and images. The window Choose Storage Volume opens which has almost identical functionality as the Storage tab described in Section 12.1, “Managing Storage with Virtual Machine Manager”.

    Tip
    Tip: Supported Storage Formats

    SUSE only supports the following storage formats: raw, qcow2, and qed.

  3. After you manage to create and specify the disk image file, specify the Device type. It can be one of the following options:

    • Disk device

    • CDROM device: Does not allow using Create a disk image for the virtual machine.

    • Floppy device: Does not allow using Create a disk image for the virtual machine.

    • LUN Passthrough: Required to use an existing SCSI storage directly without adding it into a storage pool.

  4. Select the Bus type for your device. The list of available options depends on the device type you selected in the previous step. The types based on VirtIO use paravirtualized drivers.

  5. In the Advanced options section, select the preferred Cache mode. For more information on cache modes, see Chapter 15, Disk Cache Modes.

  6. Confirm your settings with Finish. A new storage device appears in the left panel.

14.3 Controllers

This section focuses on adding and configuring new controllers.

Procedure 14.2: Adding a New Controller
  1. Click Add Hardware below the left panel, then select Controller from the Add New Virtual Hardware window.

    Add a New Controller
    Figure 14.10: Add a New Controller
  2. Select the type of the controller. You can choose from IDE, Floppy, SCSI, SATA, VirtIO Serial (paravirtualized), USB, or CCID (smart card devices).

  3. Optionally, in the case of a USB or SCSI controller, select a controller model.

  4. Confirm your settings with Finish. A new controller appears in the left panel.

14.4 Networking

This section describes how to add and configure new network devices.

Procedure 14.3: Adding a New Network Device
  1. Click Add Hardware below the left panel, then select Network from the Add New Virtual Hardware window.

    Add a New Controller
    Figure 14.11: Add a New Controller
  2. From the Network source list, select the source for the network connection. The list includes VM Host Server's available physical network interfaces, network bridges, or network bonds. You can also assign the VM Guest to an already defined virtual network. See Chapter 13, Managing Networks for more information on setting up virtual networks with Virtual Machine Manager.

  3. Specify a MAC address for the network device. While Virtual Machine Manager pre-fills a random value for your convenience, it is recommended to supply a MAC address appropriate for your network environment to avoid network conflicts.

  4. Select a device model from the list. You can either leave the Hypervisor default, or specify one of e1000, rtl8139, or virtio models. Note that virtio uses paravirtualized drivers.

  5. Confirm your settings with Finish. A new network device appears in the left panel.

14.5 Enabling Seamless and Synchronized Mouse Pointer Movement

When you click within a VM Guest's console with the mouse, the pointer is captured by the console window and cannot be used outside the console unless it is explicitly released (by pressing AltCtrl). To prevent the console from grabbing the key and to enable seamless pointer movement between host and guest instead, add a tablet to the VM Guest.

Adding a tablet has the additional advantage of synchronizing the mouse pointer movement between VM Host Server and VM Guest when using a graphical environment on the guest. With no tablet configured on the guest, you will often see two pointers with one dragging behind the other.

  1. Double-click a VM Guest entry in the Virtual Machine Manager to open its console and switch to the Details view with View › Details.

  2. Click Add Hardware and choose Input and then EvTouch USB Graphics Tablet in the pop-up window. Proceed with Finish.

  3. If the guest is running, you will be asked whether to enable the tablet after the next reboot. Confirm with Yes.

  4. When you start or restart the VM Guest, the tablet becomes available in the VM Guest.

14.6 Adding a CD/DVD-ROM Device with Virtual Machine Manager

KVM supports CD or DVD-ROMs in VM Guest either by directly accessing a physical drive on the VM Host Server or by accessing ISO images. To create an ISO image from an existing CD or DVD, use dd:

dd if=/dev/CD_DVD_DEVICE of=my_distro.iso bs=2048

To add a CD/DVD-ROM device to your VM Guest, proceed as follows:

  1. Double-click a VM Guest entry in the Virtual Machine Manager to open its console and switch to the Details view with View › Details.

  2. Click Add Hardware and choose Storage in the pop-up window.

  3. Change the Device Type to IDE CDROM.

  4. Select Select or create custom storage.

    1. To assign the device to a physical medium, enter the path to the VM Host Server's CD/DVD-ROM device (for example, /dev/cdrom) next to Manage. Alternatively, use Manage to open a file browser and then click Browse Local to select the device. Assigning the device to a physical medium is only possible when the Virtual Machine Manager was started on the VM Host Server.

    2. To assign the device to an existing image, click Manage to choose an image from a storage pool. If the Virtual Machine Manager was started on the VM Host Server, alternatively choose an image from another location on the file system by clicking Browse Local. Select an image and close the file browser with Choose Volume.

  5. Save the new virtualized device with Finish.

  6. Reboot the VM Guest to make the new device available. For more information, see Section 14.8, “Ejecting and Changing Floppy or CD/DVD-ROM Media with Virtual Machine Manager”.

14.7 Adding a Floppy Device with Virtual Machine Manager

Currently KVM only supports the use of floppy disk images—using a physical floppy drive is not supported. Create a floppy disk image from an existing floppy using dd:

dd if=/dev/fd0 of=/var/lib/libvirt/images/floppy.img

To create an empty floppy disk image use one of the following commands:

Raw Image
dd if=/dev/zero of=/var/lib/libvirt/images/floppy.img bs=512 count=2880
FAT Formatted Image
mkfs.msdos -C /var/lib/libvirt/images/floppy.img 1440

To add a floppy device to your VM Guest, proceed as follows:

  1. Double-click a VM Guest entry in the Virtual Machine Manager to open its console and switch to the Details view with View › Details.

  2. Click Add Hardware and choose Storage in the pop-up window.

  3. Change the Device Type to Floppy Disk.

  4. Choose Select or create custom storage and click Manage to choose an existing image from a storage pool. If Virtual Machine Manager was started on the VM Host Server, alternatively choose an image from another location on the file system by clicking Browse Local. Select an image and close the file browser with Choose Volume.

  5. Save the new virtualized device with Finish.

  6. Reboot the VM Guest to make the new device available. For more information, see Section 14.8, “Ejecting and Changing Floppy or CD/DVD-ROM Media with Virtual Machine Manager”.

14.8 Ejecting and Changing Floppy or CD/DVD-ROM Media with Virtual Machine Manager

Whether you are using the VM Host Server's physical CD/DVD-ROM device or an ISO/floppy image: Before you can change the media or image of an existing device in the VM Guest, you first need to disconnect the media from the guest.

  1. Double-click a VM Guest entry in the Virtual Machine Manager to open its console and switch to the Details view with View › Details.

  2. Choose the Floppy or CD/DVD-ROM device and eject the medium by clicking Disconnect.

  3. To insert a new medium, click Connect.

    1. If using the VM Host Server's physical CD/DVD-ROM device, first change the media in the device (this may require unmounting it on the VM Host Server before it can be ejected). Then choose CD-ROM or DVD and select the device from the drop-down box.

    2. If you are using an ISO image, choose ISO image Location and select an image by clicking Manage. When connecting from a remote host, you may only choose images from existing storage pools.

  4. Click OK to finish. The new media can now be accessed in the VM Guest.

14.9 Changing the Machine Type with virsh

By default, when installing with the virt-install tool, the machine type for VM Guest is pc-i440fx. The machine type is stored in the VM Guest's xml configuration file in /etc/libvirt/qemu/ in the tag type:

<type arch='x86_64' machine='pc-i440fx-2.3'>hvm</type>

As an example, the following procedure shows how to change this value to the machine type q35. q35 is an Intel* chipset. It includes PCIe, supports up to 12 USB ports, and has support for SATA and IOMMU. IRQ routing has also been improved.

  1. Check whether your VM Guest is inactive:

    virsh list --inactive
    Id    Name                           State
    ----------------------------------------------------
    -     sles11                         shut off
  2. Edit the configuration for this VM Guest:

    virsh edit sles11
  3. Change the value of the machine attribute:

    <type arch='x86_64' machine='pc-q35-2.0'>hvm</type>
  4. Restart the VM Guest.

    root # virsh start sles11
  5. Check that the machine type has changed. Log in to the VM Guest as root and run the following command:

    root # dmidecode | grep Product
    Product Name: Standard PC (Q35 + ICH9, 2009)
Tip
Tip: Machine Type Update Recommendations

Whenever the QEMU version on the host system is upgraded (for example, when upgrading the VM Host Server to a new service pack), upgrade the machine type of the VM Guests to the latest available version. To check, use the command qemu-system-x86_64 -M help on the VM Host Server.

The default machine type pc-i440fx, for example, is regularly updated. If your VM Guest still runs with a machine type of pc-i440fx-1.X, an update to pc-i440fx-2.X is strongly recommended. This allows taking advantage of the most recent updates and corrections in machine definitions, and ensures better future compatibility.

14.10 Assigning a Host PCI Device to a VM Guest

You can directly assign host-PCI devices to guests (PCI pass-through). When the PCI device is assigned to one VM Guest, it cannot be used on the host or by another VM Guest unless it is re-assigned. A prerequisite for this feature is a VM Host Server configuration as described in Important: Requirements for VFIO and SR-IOV.

14.10.1 Adding a PCI Device with Virtual Machine Manager

The following procedure describes how to add a PCI device to a VM Guest using Virtual Machine Manager:

  1. Double-click a VM Guest entry in the Virtual Machine Manager to open its console and switch to the Details view with View › Details.

  2. Click Add Hardware and choose the PCI Host Device category in the left panel. A list of available PCI devices appears in the right part of the window.

    Adding a PCI Device
    Figure 14.12: Adding a PCI Device
  3. From the list of available PCI devices, choose the one you want to pass to the guest. Confirm with Finish.

Tip
Tip: Assigning a PCI Device Requires a VM Guest Shutdown

Although it is possible to assign a PCI device to a running VM Guest as described above, the device will not become available until you shut down the VM Guest and reboot it afterward.

14.10.2 Adding a PCI Device with virsh

To assign a PCI device to VM Guest with virsh, follow these steps:

  1. Identify the host PCI device to assign to the guest. In the following example, we are assigning a DEC network card to the guest:

    tux > sudo lspci -nn
    [...]
    03:07.0 Ethernet controller [0200]: Digital Equipment Corporation DECchip \
    21140 [FasterNet] [1011:0009] (rev 22)
    [...]

    Note down the device ID (03:07.0 in this case).

  2. Gather detailed information about the device using virsh nodedev-dumpxml ID. To get the ID, you need to replace colon and period in the device ID (03:07.0) with underscore and prefix the result with pci_0000_ (pci_0000_03_07_0).

    tux > virsh nodedev-dumpxml pci_0000_03_07_0
    <device>
      <name>pci_0000_03_07_0</name>
      <path>/sys/devices/pci0000:00/0000:00:14.4/0000:03:07.0</path>
      <parent>pci_0000_00_14_4</parent>
      <driver>
        <name>tulip</name>
      </driver>
      <capability type='pci'>
        <domain>0</domain>
        <bus>3</bus>
        <slot>7</slot>
        <function>0</function>
        <product id='0x0009'>DECchip 21140 [FasterNet]</product>
        <vendor id='0x1011'>Digital Equipment Corporation</vendor>
        <numa node='0'/>
      </capability>
    </device>

    Note down the values for domain, bus, and function.

  3. Detach the device from the host system prior to attaching it to VM Guest.

    tux > virsh nodedev-detach pci_0000_03_07_0
      Device pci_0000_03_07_0 detached
    Tip
    Tip: Multi-Function PCI Devices

    When using a multi-function PCI device that does not support FLR (function level reset) or PM (power management) reset, you need to detach all its functions from the VM Host Server. The whole device must be reset for security reasons. libvirt will refuse to assign the device if one of its functions is still in use by the VM Host Server or another VM Guest.

  4. Convert the domain, bus, slot, and function value from decimal to hexadecimal, and prefix with 0x to tell the system that the value is hexadecimal. In our example, domain = 0, bus = 3, slot = 7, and function = 0. Their hexadecimal values are:

    tux > printf %x 0
    0
    tux > printf %x 3
    3
    tux > printf %x 7
    7

    This results in domain = 0x0000, bus = 0x03, slot = 0x07 and function = 0x00.

  5. Run virsh edit on your domain, and add the following device entry in the <devices> section using the values from the previous step:

    <hostdev mode='subsystem' type='pci' managed='yes'>
      <source>
        <address domain='0x0000' bus='0x03' slot='0x07' function='0x00'/>
      </source>
    </hostdev>
    Tip
    Tip: managed Compared to unmanaged

    libvirt recognizes two modes for handling PCI devices: they can be either managed or unmanaged. In the managed case, libvirt will do handle all details of unbinding the device from the existing driver if needed, resetting the device, binding it to vfio-pci before starting the domain, etc. When the domain is terminated or the device is removed from the domain, libvirt will unbind from vfio-pci and rebind to the original driver in the case of a managed device. If the device is unmanaged, the user must ensure all of these management aspects of the device are done before assigning it to a domain, and after the device is no longer used by the domain.

    In the example above, the managed='yes' option means that the device is managed. To switch the device mode to unmanaged, set managed='no' in the listing above. If you do so, you need to take care of the related driver with the virsh nodedev-detach and virsh nodedev-reattach commands. That means you need to run virsh nodedev-detach pci_0000_03_07_0 prior to starting the VM Guest to detach the device from the host. In case the VM Guest is not running, you can make the device available for the host by running virsh nodedev-reattach pci_0000_03_07_0.

  6. Shut down the VM Guest and restart it to make the assigned PCI device available.

    Tip
    Tip: SELinux

    If you are running SELinux on your VM Host Server, you need to disable it prior to starting the VM Guest with

    setsebool -P virt_use_sysfs 1

14.11 Assigning a Host USB Device to a VM Guest

Analogous to assigning host PCI devices (see Section 14.10, “Assigning a Host PCI Device to a VM Guest”), you can directly assign host USB devices to guests. When the USB device is assigned to one VM Guest, it cannot be used on the host or by another VM Guest unless it is re-assigned.

14.11.1 Adding a USB Device with Virtual Machine Manager

To assign a host USB device to VM Guest using Virtual Machine Manager, follow these steps:

  1. Double-click a VM Guest entry in the Virtual Machine Manager to open its console and switch to the Details view with View › Details.

  2. Click Add Hardware and choose the USB Host Device category in the left panel. A list of available USB devices appears in the right part of the window.

    Adding a USB Device
    Figure 14.13: Adding a USB Device
  3. From the list of available USB devices, choose the one you want to pass to the guest. Confirm with Finish. The new USB device appears in the left pane of the Details view.

    Tip
    Tip: USB Device Removal

    To remove the host USB device assignment, click it in the left pane of the Details view and confirm with Remove.

14.11.2 Adding a USB Device with virsh

To assign a USB device to VM Guest using virsh, follow these steps:

  1. Identify the host USB device to assign to the guest:

    tux > sudo lsusb
    [...]
    Bus 001 Device 003: ID 0557:2221 ATEN International Co., Ltd Winbond Hermon
    [...]

    Note down the vendor and product IDs. In our example, the vendor ID is 0557 and the product ID is 2221.

  2. Run virsh edit on your domain, and add the following device entry in the <devices> section using the values from the previous step:

    <hostdev mode='subsystem' type='usb'>
      <source startupPolicy='optional'>
       <vendor id='0557'/>
       <product id='2221'/>
      </source>
    </hostdev>
    Tip
    Tip: Vendor/Product or Device's Address

    Instead of defining the host device with <vendor/> and <product/> IDs, you can use the <address/> element as described for host PCI devices in Section 14.10.2, “Adding a PCI Device with virsh.

  3. Shut down the VM Guest and restart it to make the assigned USB device available.

    Tip
    Tip: SELinux

    If you are running SELinux on your VM Host Server, you need to disable it prior to starting the VM Guest with

    setsebool -P virt_use_sysfs 1

14.12 Adding SR-IOV Devices

Single Root I/O Virtualization (SR-IOV) capable PCIe devices can replicate their resources, so they appear to be multiple devices. Each of these "pseudo-devices" can be assigned to a VM Guest.

SR-IOV is an industry specification that was created by the Peripheral Component Interconnect Special Interest Group (PCI-SIG) consortium. It introduces physical functions (PF) and virtual functions (VF). PFs are full PCIe functions used to manage and configure the device. PFs also can move data. VFs lack the configuration and management part—they only can move data and a reduced set of configuration functions. Since VFs do not have all PCIe functions, the host operating system or the Hypervisor must support SR-IOV to be able to access and initialize VFs. The theoretical maximum for VFs is 256 per device (consequently the maximum for a dual-port Ethernet card would be 512). In practice this maximum is much lower, since each VF consumes resources.

14.12.1 Requirements

The following requirements must be met to be able to use SR-IOV:

  • An SR-IOV-capable network card (as of SUSE Linux Enterprise Server 12 SP3, only network cards support SR-IOV)

  • An AMD64/Intel 64 host supporting hardware virtualization (AMD-V or Intel VT-x), see Section 7.3, “KVM Hardware Requirements” for more information

  • A chipset that supports device assignment (AMD-Vi or Intel VT-d)

  • libvirt-0.9.10 or better

  • SR-IOV drivers must be loaded and configured on the host system

  • A host configuration that meets the requirements listed at Important: Requirements for VFIO and SR-IOV

  • A list of the PCI addresses of the VF(s) that will be assigned to VM Guests

Tip
Tip: Checking if a Device is SR-IOV-Capable

The information whether a device is SR-IOV-capable can be obtained from its PCI descriptor by running lspci. A device that supports SR-IOV reports a capability similar to the following:

Capabilities: [160 v1] Single Root I/O Virtualization (SR-IOV)
Note
Note: Adding an SR-IOV Device at VM Guest Creation

Before adding an SR-IOV device to a VM Guest when initially setting it up, the VM Host Server already needs to be configured as described in Section 14.12.2, “Loading and Configuring the SR-IOV Host Drivers”.

14.12.2 Loading and Configuring the SR-IOV Host Drivers

To be able to access and initialize VFs, an SR-IOV-capable driver needs to be loaded on the host system.

  1. Before loading the driver, make sure the card is properly detected by running lspci. The following example shows the lspci output for the dual-port Intel 82576NS network card:

    tux > sudo /sbin/lspci | grep 82576
    01:00.0 Ethernet controller: Intel Corporation 82576NS Gigabit Network Connection (rev 01)
    01:00.1 Ethernet controller: Intel Corporation 82576NS Gigabit Network Connection (rev 01)
    04:00.0 Ethernet controller: Intel Corporation 82576NS Gigabit Network Connection (rev 01)
    04:00.1 Ethernet controller: Intel Corporation 82576NS Gigabit Network Connection (rev 01)

    In case the card is not detected, it is likely that the hardware virtualization support in the BIOS/EFI has not been enabled.

  2. Check whether the SR-IOV driver is already loaded by running lsmod. In the following example a check for the igb driver (for the Intel 82576NS network card) returns a result. That means the driver is already loaded. If the command returns nothing, the driver is not loaded.

    tux > sudo /sbin/lsmod | egrep "^igb "
    igb                   185649  0
  3. Skip this step if the driver is already loaded.

    If the SR-IOV driver is not yet loaded, the non-SR-IOV driver needs to be removed first, before loading the new driver. Use rmmod to unload a driver. The following example unloads the non-SR-IOV driver for the Intel 82576NS network card:

    sudo /sbin/rmmod igbvf

    Load the SR-IOV driver subsequently using the modprobe command—the VF parameter (max_vfs) is mandatory:

    sudo /sbin/modprobe igb max_vfs=8

    Or load the driver via SYSFS:

    Find the PCI ID of the physical NIC by listing Ethernet devices:

    tux > sudo lspci | grep Eth
    06:00.0 Ethernet controller: Emulex Corporation OneConnect NIC (Skyhawk) (rev 10)
    06:00.1 Ethernet controller: Emulex Corporation OneConnect NIC (Skyhawk) (rev 10)

    To enable VFs, echo the number of desired VFs to load to the sriov_numvfs parameter:

    tux > sudo echo 1 > /sys/bus/pci/devices/0000:06:00.1/sriov_numvfs

    Verify that the VF NIC was loaded:

    tux > sudo lspci | grep Eth
    06:00.0 Ethernet controller: Emulex Corporation OneConnect NIC (Skyhawk) (rev 10)
    06:00.1 Ethernet controller: Emulex Corporation OneConnect NIC (Skyhawk) (rev 10)
    06:08.0 Ethernet controller: Emulex Corporation OneConnect NIC (Skyhawk) (rev 10)

    Obtain the maximum number of VFs available:

    tux > sudo lspci -vvv -s 06:00.1 | grep 'Initial VFs'
                           Initial VFs: 32, Total VFs: 32, Number of VFs: 0,
    Function Dependency Link: 01
  4. Create a before.service file which loads VF via SYSFS on boot:

    [Unit]
    Before=
    [Service]
    Type=oneshot
    RemainAfterExit=true
    ExecStart=/bin/bash -c "echo 1 > /sys/bus/pci/devices/0000:06:00.1/sriov_numvfs"
    # beware, executable is run directly, not through a shell, check the man pages
    # systemd.service and systemd.unit for full syntax
    [Install]
    # target in which to start the service
    WantedBy=multi-user.target
    #WantedBy=graphical.target

    And copy it to /etc/systemd/system.

    Additionally, it is required to create another service file (after-local.service) pointing to /etc/init.d/after.local script that detaches the NIC prior to starting the VM, otherwise the VM would fail to start:

    [Unit]
    Description=/etc/init.d/after.local Compatibility
    After=libvirtd.service
    Requires=libvirtd.service
    [Service]
    Type=oneshot
    ExecStart=/etc/init.d/after.local
    RemainAfterExit=true
    
    [Install]
    WantedBy=multi-user.target

    And copy it to /etc/systemd/system.

    #! /bin/sh
    #
    # Copyright (c) 2010 SuSE LINUX Products GmbH, Germany.  All rights reserved.
    # ...
    virsh nodedev-detach pci_0000_06_08_0

    Then save it as /etc/init.d/after.local.

  5. Reboot the machine and check if the SR-IOV driver is loaded by re-running the lspci command from the first step of this procedure. If the SR-IOV driver was loaded successfully you should see additional lines for the VFs:

    01:00.0 Ethernet controller: Intel Corporation 82576NS Gigabit Network Connection (rev 01)
    01:00.1 Ethernet controller: Intel Corporation 82576NS Gigabit Network Connection (rev 01)
    01:10.0 Ethernet controller: Intel Corporation 82576 Virtual Function (rev 01)
    01:10.1 Ethernet controller: Intel Corporation 82576 Virtual Function (rev 01)
    01:10.2 Ethernet controller: Intel Corporation 82576 Virtual Function (rev 01)
    [...]
    04:00.0 Ethernet controller: Intel Corporation 82576NS Gigabit Network Connection (rev 01)
    04:00.1 Ethernet controller: Intel Corporation 82576NS Gigabit Network Connection (rev 01)
    04:10.0 Ethernet controller: Intel Corporation 82576 Virtual Function (rev 01)
    04:10.1 Ethernet controller: Intel Corporation 82576 Virtual Function (rev 01)
    04:10.2 Ethernet controller: Intel Corporation 82576 Virtual Function (rev 01)
    [...]

14.12.3 Adding a VF Network Device to an Existing VM Guest

When the SR-IOV hardware is properly set up on the VM Host Server, you can add VFs to VM Guests. To do so, you need to collect some data first.

Note: The following procedure is using example data. Make sure to replace it by appropriate data from your setup.

  1. Use the virsh nodedev-list command to get the PCI address of the VF you want to assign and its corresponding PF. Numerical values from the lspci output shown in Section 14.12.2, “Loading and Configuring the SR-IOV Host Drivers” (for example 01:00.0 or 04:00.1) are transformed by adding the prefix "pci_0000_" and by replacing colons and dots with underscores. So a PCI ID listed as "04:00.0" by lspci is listed as "pci_0000_04_00_0" by virsh. The following example lists the PCI IDs for the second port of the Intel 82576NS network card:

    tux > sudo virsh nodedev-list | grep 0000_04_
    pci_0000_04_00_0
    pci_0000_04_00_1
    pci_0000_04_10_0
    pci_0000_04_10_1
    pci_0000_04_10_2
    pci_0000_04_10_3
    pci_0000_04_10_4
    pci_0000_04_10_5
    pci_0000_04_10_6
    pci_0000_04_10_7
    pci_0000_04_11_0
    pci_0000_04_11_1
    pci_0000_04_11_2
    pci_0000_04_11_3
    pci_0000_04_11_4
    pci_0000_04_11_5

    The first two entries represent the PFs, whereas the other entries represent the VFs.

  2. Get more data that will be needed by running the command virsh nodedev-dumpxml on the PCI ID of the VF you want to add:

    tux > sudo virsh nodedev-dumpxml pci_0000_04_10_0
    <device>
      <name>pci_0000_04_10_0</name>
      <parent>pci_0000_00_02_0</parent>
      <capability type='pci'>
        <domain>0</domain>
        <bus>4</bus>
        <slot>16</slot>
        <function>0</function>
        <product id='0x10ca'>82576 Virtual Function</product>
        <vendor id='0x8086'>Intel Corporation</vendor>
        <capability type='phys_function'>
          <address domain='0x0000' bus='0x04' slot='0x00' function='0x0'/>
        </capability>
      </capability>
    </device>

    The following data is needed for the next step:

    • <domain>0</domain>

    • <bus>4</bus>

    • <slot>16</slot>

    • <function>0</function>

  3. Create a temporary XML file (for example /tmp/vf-interface.xml containing the data necessary to add a VF network device to an existing VM Guest. The minimal content of the file needs to look like the following:

    <interface type='hostdev'>1
     <source>
      <address type='pci' domain='0' bus='11' slot='16' function='0'2/>2
     </source>
    </interface>

    1

    VFs do not get a fixed MAC address; it changes every time the host reboots. When adding network devices the traditional way with <hostdev>, it would require to reconfigure the VM Guest's network device after each reboot of the host, because of the MAC address change. To avoid this kind of problem, libvirt introduced the interface type='hostdev' directive, which sets up network-specific data before assigning the device.

    2

    Specify the data you acquired in the previous step here.

  4. In case a device is already attached to the host, it cannot be attached to a guest. To make it available for guests, detach it from the host first:

    virsh nodedev-detach pci_0000_04_10_0
  5. Last, add the VF interface to an existing VM Guest:

    virsh attach-device GUEST /tmp/vf-interface.xml --OPTION

    GUEST needs to be replaced by the domain name, id or uuid of the VM Guest and --OPTION can be one of the following:

    --persistent

    This option will always add the device to the domain's persistent XML. In addition, if the domain is running, it will be hotplugged.

    --config

    This option will only affect the persistent XML, even if the domain is running. The device will only show up in the guest on next boot.

    --live

    This option will only affect a running domain. If the domain is inactive, the operation will fail. The device is not persisted in the XML and will not be available in the guest on next boot.

    --current

    This option affects the current state of the domain. If the domain is inactive, the device is added to the persistent XML and will be available on next boot. If the domain is active, the device is hotplugged but not added to the persistent XML.

    To detach a VF interface, use the virsh detach-device command, which also takes the options listed above.

14.12.4 Dynamic Allocation of VFs from a Pool

If you define the PCI address of a VF into a guest's configuration statically as described in Section 14.12.3, “Adding a VF Network Device to an Existing VM Guest”, it is hard to migrate such guest to another host. The host must have identical hardware in the same location on the PCI bus, or the guest configuration must be modified prior to each start.

Another approach is to create a libvirt network with a device pool that contains all the VFs of an SR-IOV device. The guest then references this network, and each time it is started, a single VF is dynamically allocated to it. When the guest is stopped, the VF is returned to the pool, available for another guest.

14.12.4.1 Defining Network with Pool of VFs on VM Host Server

The following example of network definition creates a pool of all VFs for the SR-IOV device with its physical function (PF) at the network interface eth0 on the host:

<network>
  <name>passthrough</name>
    <forward mode='hostdev' managed='yes'>
      <pf dev='eth0'/>
    </forward>
  </network>

To use this network on the host, save the above code to a file, for example /tmp/passthrough.xml, and execute the following commands. Remember to replace eth0 with the real network interface name of your SR-IOV device's PF:

virsh net-define /tmp/passthrough.xml
virsh net-autostart passthrough
virsh net-start passthrough

14.12.4.2 Configuring VM Guest to Use VF from the Pool

The following example of guest device interface definition uses a VF of the SR-IOV device from the pool created in Section 14.12.4.1, “Defining Network with Pool of VFs on VM Host Server”. libvirt automatically derives the list of all VFs associated with that PF the first time the guest is started.

<interface type='network'>
  <source network='passthrough'>
</interface>

To verify the list of associated VFs, run virsh net-dumpxml passthrough on the host after the first guest that uses the network with the pool of VFs starts.

<network connections='1'>
  <name>passthrough</name>
  <uuid>a6a26429-d483-d4ed-3465-4436ac786437</uuid>
  <forward mode='hostdev' managed='yes'>
    <pf dev='eth0'/>
    <address type='pci' domain='0x0000' bus='0x02' slot='0x10' function='0x1'/>
    <address type='pci' domain='0x0000' bus='0x02' slot='0x10' function='0x3'/>
    <address type='pci' domain='0x0000' bus='0x02' slot='0x10' function='0x5'/>
    <address type='pci' domain='0x0000' bus='0x02' slot='0x10' function='0x7'/>
    <address type='pci' domain='0x0000' bus='0x02' slot='0x11' function='0x1'/>
    <address type='pci' domain='0x0000' bus='0x02' slot='0x11' function='0x3'/>
    <address type='pci' domain='0x0000' bus='0x02' slot='0x11' function='0x5'/>
  </forward>
  </network>

14.13 Using Macvtap to Share VM Host Server Network Interfaces

Macvtap provides direct attachment of a VM Guest virtual interface to a host network interface. The macvtap-based interface extends the VM Host Server network interface and has its own MAC address on the same Ethernet segment. Typically, this is used to make both the VM Guest and the VM Host Server show up directly on the switch that the VM Host Server is connected to.

Note
Note: Macvtap Cannot Be Used With a Linux Bridge

Macvtap cannot be used with network interfaces already connected to a linux bridge. Before attempting to create the macvtap interface, remove the interface from the bridge.

Note
Note: VM Guest to VM Host Server Communication with Macvtap

When using macvtap, a VM Guest can communicate with other VM Guests, and with other external hosts on the network. But it cannot communicate with the VM Host Server on which the VM Guest runs. This is the defined behavior of macvtap, because of the way the VM Host Server's physical Ethernet is attached to the macvtap bridge. Traffic from the VM Guest into that bridge that is forwarded to the physical interface cannot be bounced back up to the VM Host Server's IP stack. Similarly, traffic from the VM Host Server's IP stack that is sent to the physical interface cannot be bounced back up to the macvtap bridge for forwarding to the VM Guest.

Virtual network interfaces based on macvtap are supported by libvirt by specifying an interface type of direct. For example:

<interface type='direct'>
  <mac address='aa:bb:cc:dd:ee:ff'/>
  <source dev='eth0' mode='bridge'/>
  <model type='virtio'/>
  </interface>

The operation mode of the macvtap device can be controlled with the mode attribute. The following lists shows its possible values and a description for each:

  • vepa: All VM Guest packets are sent to an external bridge. Packets whose destination is a VM Guest on the same VM Host Server as where the packet originates from are sent back to the VM Host Server by the VEPA capable bridge (today's bridges are typically not VEPA capable).

  • bridge: Packets whose destination is on the same VM Host Server where they originate from are directly delivered to the target macvtap device. Both origin and destination devices need to be in bridge mode for direct delivery. If either one of them is in vepa mode, a VEPA capable bridge is required.

  • private: All packets are sent to the external bridge and will only be delivered to a target VM Guest on the same VM Host Server if they are sent through an external router or gateway and that device sends them back to the VM Host Server. This procedure is followed if either the source or destination device is in private mode.

  • passthrough: A special mode that gives more power to the network interface. All packets will be forwarded to the interface, allowing virtio VM Guests to change the MAC address or set promiscuous mode to bridge the interface or create VLAN interfaces on top of it. Note that a network interface is not shareable in passthrough mode. Assigning an interface to a VM Guest will disconnect it from the VM Host Server. For this reason SR-IOV virtual functions are often assigned to the VM Guest in passthrough mode.

Part III Hypervisor-Independent Features

15 Disk Cache Modes

16 VM Guest Clock Settings

Keeping the correct time in a VM Guest is one of the more difficult aspects of virtualization. Keeping the correct time is especially important for network applications and is also a prerequisite to do a live migration of a VM Guest.

17 libguestfs

Virtual Machines consist of disk images and definition files. Manually accessing and manipulating these guest components (outside of normal hypervisor processes) is possible, but inherently dangerous and risks compromising data integrity. libguestfs is a C library and a corresponding set of tools designed for safely accessing and modifying Virtual Machine disk images—outside of normal hypervisor processes, but without the risk normally associated with manual editing.

15 Disk Cache Modes

  • Filename: vt_cachemodes.xml
  • ID: cha.cachemodes

15.1 Disk Interface Cache Modes

Hypervisors allow for various storage caching strategies to be specified when configuring a VM Guest. Each guest disk interface can have one of the following cache modes specified: writethrough, writeback, none, directsync, or unsafe. If no cache mode is specified, an appropriate default cache mode is used. These cache modes influence how host-based storage is accessed, as follows:

  • Read/write data may be cached in the host page cache.

  • The guest's storage controller is informed whether a write cache is present, allowing for the use of a flush command.

  • Synchronous write mode may be used, in which write requests are reported complete only when committed to the storage device.

  • Flush commands (generated by the guest storage controller) may be ignored for performance reasons.

If a disorderly disconnection between the guest and its storage occurs, the cache mode in use will affect whether data loss occurs. The cache mode can also affect disk performance significantly. Additionally, some cache modes are incompatible with live migration, depending on several factors. There are no simple rules about what combination of cache mode, disk image format, image placement, or storage sub-system is best. The user should plan each guest's configuration carefully and experiment with various configurations to determine the optimal performance.

15.2 Description of Cache Modes

cache mode unspecified

In older QEMU versions, not specifying a cache mode meant that writethrough would be used as the default. With modern versions—as shipped with SUSE Linux Enterprise Server—the various guest storage interfaces have been fixed to handle writeback or writethrough semantics more correctly. This allows for the default caching mode to be switched to writeback. The guest driver for each of ide, scsi, and virtio have within their power to disable the write back cache, causing the caching mode used to revert to writethrough. The typical guest's storage drivers will maintain the default caching mode as writeback, however.

writethrough

This mode causes the hypervisor to interact with the disk image file or block device with O_DSYNC semantics. Writes are reported as completed only when the data has been committed to the storage device. The host page cache is used in what can be termed a writethrough caching mode. The guest's virtual storage adapter is informed that there is no writeback cache, so the guest would not need to send down flush commands to manage data integrity. The storage behaves as if there is a writethrough cache.

writeback

This mode causes the hypervisor to interact with the disk image file or block device with neither O_DSYNC nor O_DIRECT semantics. The host page cache is used and writes are reported to the guest as completed when they are placed in the host page cache. The normal page cache management will handle commitment to the storage device. Additionally, the guest's virtual storage adapter is informed of the writeback cache, so the guest would be expected to send down flush commands as needed to manage data integrity. Analogous to a raid controller with RAM cache.

none

This mode causes the hypervisor to interact with the disk image file or block device with O_DIRECT semantics. The host page cache is bypassed and I/O happens directly between the hypervisor user space buffers and the storage device. Because the actual storage device may report a write as completed when placed in its write queue only, the guest's virtual storage adapter is informed that there is a writeback cache. The guest would be expected to send down flush commands as needed to manage data integrity. Performance-wise, it is equivalent to direct access to your host's disk.

unsafe

This mode is similar to the writeback mode discussed above. The key aspect of this unsafe mode, is that all flush commands from the guests are ignored. Using this mode implies that the user has accepted the trade-off of performance over risk of data loss in case of a host failure. Useful, for example, during guest installation, but not for production workloads.

directsync

This mode causes the hypervisor to interact with the disk image file or block device with both O_DSYNC and O_DIRECT semantics. This means, writes are reported as completed only when the data has been committed to the storage device, and when it is also desirable to bypass the host page cache. Like writethrough, it is helpful to guests that do not send flushes when needed. It was the last cache mode added, completing the possible combinations of caching and direct access semantics.

15.3 Data Integrity Implications of Cache Modes

writethrough, none, directsync

These are the safest modes, and considered equally safe, given that the guest operating system is modern and well behaved, which means that it uses flushes as needed. If you have a suspect guest, use writethough, or directsync. Note that some file systems are not compatible with none or directsync, as they do not support O_DIRECT, which these cache modes rely on.

writeback

This mode informs the guest of the presence of a write cache, and relies on the guest to send flush commands as needed to maintain data integrity within its disk image. This is a common storage design which is completely accounted for within modern file systems. This mode exposes the guest to data loss in the unlikely case of a host failure, because there is a window of time between the time a write is reported as completed, and that write being committed to the storage device.

unsafe

This mode is similar to writeback caching except for the following: the guest flush commands are ignored, nullifying the data integrity control of these flush commands, and resulting in a higher risk of data loss because of host failure. The name unsafe should serve as a warning that there is a much higher potential for data loss because of a host failure than with the other modes. As the guest terminates, the cached data is flushed at that time.

15.4 Performance Implications of Cache Modes

The choice to make full use of the page cache, or to write through it, or to bypass it altogether can have dramatic performance implications. Other factors that influence disk performance include the capabilities of the actual storage system, what disk image format is used, the potential size of the page cache and the IO scheduler used. Additionally, not flushing the write cache increases performance, but with risk, as noted above. As a general rule, high-end systems typically perform best with the cache mode none, because of the reduced data copying that occurs. The potential benefit of having multiple guests share the common host page cache, the ratio of reads to writes, and the use of AIO mode native (see below) should also be considered.

15.5 Effect of Cache Modes on Live Migration

The caching of storage data and metadata restricts the configurations that support live migration. Currently, only raw, qcow2 and qed image formats can be used for live migration. If a clustered file system is used, all cache modes support live migration. Otherwise the only cache mode that supports live migration on read/write shared storage is none.

The libvirt management layer includes checks for migration compatibility based on several factors. If the guest storage is hosted on a clustered file system, is read-only or is marked shareable, then the cache mode is ignored when determining if migration can be allowed. Otherwise libvirt will not allow migration unless the cache mode is set to none. However, this restriction can be overridden with the unsafe option to the migration APIs, which is also supported by virsh, as for example in

virsh migrate --live --unsafe
Tip
Tip

The cache mode none is required for the AIO mode setting native. If another cache mode is used, then the AIO mode will silently be switched back to the default threads. The guest flush within the host is implemented using fdatasync().

16 VM Guest Clock Settings

  • Filename: vt_clocksettings.xml
  • ID: sec.kvm.managing.clock
Abstract

Keeping the correct time in a VM Guest is one of the more difficult aspects of virtualization. Keeping the correct time is especially important for network applications and is also a prerequisite to do a live migration of a VM Guest.

Tip
Tip: Timekeeping on the VM Host Server

It is strongly recommended to ensure the VM Host Server keeps the correct time as well, for example, by using NTP (see Chapter 24, Time Synchronization with NTP for more information).

16.1 KVM: Using kvm_clock

KVM provides a paravirtualized clock which is supported via the kvm_clock driver. It is strongly recommended to use kvm_clock.

Use the following command inside a VM Guest running Linux to check whether the driver kvm_clock has been loaded:

tux > sudo dmesg | grep kvm-clock
[    0.000000] kvm-clock: cpu 0, msr 0:7d3a81, boot clock
[    0.000000] kvm-clock: cpu 0, msr 0:1206a81, primary cpu clock
[    0.012000] kvm-clock: cpu 1, msr 0:1306a81, secondary cpu clock
[    0.160082] Switching to clocksource kvm-clock

To check which clock source is currently used, run the following command in the VM Guest. It should output kvm-clock:

tux > cat /sys/devices/system/clocksource/clocksource0/current_clocksource
Important
Important: kvm-clock and NTP

When using kvm-clock, it is recommended to use NTP in the VM Guest, as well. Using NTP on the VM Host Server is also recommended.

16.1.1 Other Timekeeping Methods

The paravirtualized kvm-clock is currently not for Windows* operating systems. For Windows*, use the Windows Time Service Tools for time synchronization (see http://technet.microsoft.com/en-us/library/cc773263%28WS.10%29.aspx for more information).

16.2 Xen Virtual Machine Clock Settings

With Xen 4, the independent wallclock setting /proc/sys/xen/independent_wallclock used for time synchronization between Xen host and guest was removed. A new configuration option tsc_mode was introduced. It specifies a method of utilizing the timestamp counter to synchronize the guest time with the Xen server. Its default value '0' handles the vast majority of hardware and software environments.

For more details on tsc_mode, see the xen-tscmode manual page (man 7 xen-tscmode).

17 libguestfs

  • Filename: vt_guestfs.xml
  • ID: chap.guestfs
Abstract

Virtual Machines consist of disk images and definition files. Manually accessing and manipulating these guest components (outside of normal hypervisor processes) is possible, but inherently dangerous and risks compromising data integrity. libguestfs is a C library and a corresponding set of tools designed for safely accessing and modifying Virtual Machine disk images—outside of normal hypervisor processes, but without the risk normally associated with manual editing.

17.1 VM Guest Manipulation Overview

17.1.1 VM Guest Manipulation Risk

As disk images and definition files are simply another type of file in a Linux environment, it is possible to use many tools to access, edit and write to these files. When used correctly, such tools can be an important part of guest administration. However, even correct usage of these tools is not without risk. Risks that should be considered when manually manipulating guest disk images include:

  • Data Corruption: Concurrently accessing images, by the host machine or another node in a cluster, can cause changes to be lost or data corruption to occur if virtualization protection layers are bypassed.

  • Security: Mounting disk images as loop devices requires root access. While an image is loop mounted, other users and processes can potentially access the disk contents.

  • Administrator Error: Bypassing virtualization layers correctly requires advanced understanding of virtual components and tools. Failing to isolate the images or failing to clean up properly after changes have been made can lead to further problems once back in virtualization control.

17.1.2 libguestfs Design

libguestfs C library has been designed to safely and securely create, access and modify virtual machine (VM Guest) disk images. It also provides additional language bindings: for Perl, Python, PHP (only for 64-bit machines), and Ruby. libguestfs can access VM Guest disk images without needing root and with multiple layers of defense against rogue disk images.

libguestfs provides many tools designed for accessing and modifying VM Guest disk images and contents. These tools provide such capabilities as: viewing and editing files inside guests, scripting changes to VM Guests, monitoring disk used/free statistics, creating guests, doing V2V or P2V migrations, performing backups, cloning VM Guests, formatting disks, and resizing disks.

Warning
Warning: Best Practices

You must not use libguestfs tools on live virtual machines. Doing so will probably result in disk corruption in the VM Guest. libguestfs tools try to stop you from doing this, but cannot catch all cases.

However most command have the --ro (read-only) option. With this option, you can attach a command to a live virtual machine. The results might be strange or inconsistent at times but you will not risk disk corruption.

17.2 Package Installation

libguestfs is shipped through 4 packages:

  • libguestfs0: which provides the main C library

  • guestfs-data: which contains the appliance files used when launching images (stored in /usr/lib64/guestfs)

  • guestfs-tools: the core guestfs tools, man pages, and the /etc/libguestfs-tools.conf configuration file.

  • guestfs-winsupport: provides support for Windows file guests in the guestfs tools. This package only needs to be installed to handle Windows guests, for example when converting a Windows guest to KVM.

To install guestfs tools on your system run:

zypper in guestfs-tools

17.3 Guestfs Tools

17.3.1 Modifying Virtual Machines

The set of tools found within the guestfs-tools package is used for accessing and modifying virtual machine disk images. This functionality is provided through a familiar shell interface with built-in safeguards which ensure image integrity. Guestfs tools shells expose all capabilities of the guestfs API, and create an appliance on the fly using the packages installed on the machine and the files found in /usr/lib4/guestfs.

17.3.2 Supported File Systems and Disk Images

Guestfs tools support various file systems including:

  • Ext2, Ext3, Ext4

  • Xfs

  • Btrfs

Multiple disk image formats are also supported:

  • raw

  • qcow2

Warning
Warning: Unsupported File System

Guestfs may also support Windows* file systems (VFAT, NTFS), BSD* and Apple* file systems, and other disk image formats (VMDK, VHDX...). However, these file systems and disk image formats are unsupported on SUSE Linux Enterprise.

17.3.3 virt-rescue

virt-rescue is similar to a rescue CD, but for virtual machines, and without the need for a CD. virt-rescue presents users with a rescue shell and some simple recovery tools which can be used to examine and correct problems within a virtual machine or disk image.

tux >  virt-rescue -a sles.qcow2
Welcome to virt-rescue, the libguestfs rescue shell.

Note: The contents of / are the rescue appliance.
You need to mount the guest's partitions under /sysroot
before you can examine them. A helper script for that exists:
mount-rootfs-and-do-chroot.sh /dev/sda2

><rescue>
[   67.194384] EXT4-fs (sda1): mounting ext3 file system
using the ext4 subsystem
[   67.199292] EXT4-fs (sda1): mounted filesystem with ordered data
mode. Opts: (null)
mount: /dev/sda1 mounted on /sysroot.
mount: /dev bound on /sysroot/dev.
mount: /dev/pts bound on /sysroot/dev/pts.
mount: /proc bound on /sysroot/proc.
mount: /sys bound on /sysroot/sys.
Directory: /root
Thu Jun  5 13:20:51 UTC 2014
(none):~ #

You are now running the VM Guest in rescue mode:

(none):~ # cat /etc/fstab
devpts  /dev/pts          devpts  mode=0620,gid=5 0 0
proc    /proc             proc    defaults        0 0
sysfs   /sys              sysfs   noauto          0 0
debugfs /sys/kernel/debug debugfs noauto          0 0
usbfs   /proc/bus/usb     usbfs   noauto          0 0
tmpfs   /run              tmpfs   noauto          0 0
/dev/disk/by-id/ata-QEMU_HARDDISK_QM00001-part1 / ext3 defaults 1 1

17.3.4 virt-resize

virt-resize is used to resize a virtual machine disk, making it larger or smaller overall, and resizing or deleting any partitions contained within.

Procedure 17.1: Expanding a Disk

Full step-by-step example: How to expand a virtual machine disk

  1. First, with virtual machine powered off, determine the size of the partitions available on this virtual machine:

    tux >  virt-filesystems --long --parts --blkdevs -h -a sles.qcow2
    Name       Type       MBR  Size  Parent
    /dev/sda1  partition  83   16G   /dev/sda
    /dev/sda   device     -    16G   -
  2. virt-resize cannot do in-place disk modifications—there must be sufficient space to store the resized output disk. Use the truncate command to create a file of suitable size:

    tux >  truncate -s 32G outdisk.img
  3. Use virt-resize to resize the disk image. virt-resize requires two mandatory parameters for the input and output images:

    tux >  virt-resize --expand /dev/sda1 sles.qcow2 outdisk.img
    Examining sles.qcow2 ...
    **********
    Summary of changes:
    
    /dev/sda1: This partition will be resized from 16,0G to 32,0G.  The
        filesystem ext3 on /dev/sda1 will be expanded using the 'resize2fs'
        method.
    
    **********
    Setting up initial partition table on outdisk.img ...
    Copying /dev/sda1 ...
    ◐ 84%
    ⟦▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒════════⟧ 00:03
    Expanding /dev/sda1 using the 'resize2fs' method ...
    
    Resize operation completed with no errors.  Before deleting the old
    disk, carefully check that the resized disk boots and works correctly.
  4. Confirm the image was resized properly:

    tux >  virt-filesystems --long --parts --blkdevs -h -a outdisk.img
    Name       Type       MBR  Size  Parent
    /dev/sda1  partition  83   32G   /dev/sda
    /dev/sda   device     -    32G   -
  5. Bring up the VM Guest using the new disk image and confirm correct operation before deleting the old image.

17.3.5 Other virt-* Tools

There are guestfs tools to simplify administrative tasks—such as viewing and editing files, or obtaining information on the virtual machine.

17.3.5.1 virt-filesystems

This tool is used to report information regarding file systems, partitions, and logical volumes in a disk image or virtual machine.

tux >  virt-filesystems -l -a sles.qcow2
Name       Type        VFS   Label  Size         Parent
/dev/sda1  filesystem  ext3  -      17178820608  -

17.3.5.2 virt-ls

virt-ls lists file names, file sizes, checksums, extended attributes and more from a virtual machine or disk image. Multiple directory names can be given, in which case the output from each is concatenated. To list directories from a libvirt guest, use the -d option to specify the name of the guest. For a disk image, use the -a option.

tux >  virt-ls -h -lR -a sles.qcow2 /var/log/
d 0755        776 /var/log
- 0640          0 /var/log/NetworkManager
- 0644        23K /var/log/Xorg.0.log
- 0644        23K /var/log/Xorg.0.log.old
d 0700        482 /var/log/YaST2
- 0644        512 /var/log/YaST2/_dev_vda
- 0644         59 /var/log/YaST2/arch.info
- 0644        473 /var/log/YaST2/config_diff_2017_05_03.log
- 0644       5.1K /var/log/YaST2/curl_log
- 0644       1.5K /var/log/YaST2/disk_vda.info
- 0644       1.4K /var/log/YaST2/disk_vda.info-1
[...]

17.3.5.3 virt-cat

virt-cat is a command line tool to display the contents of a file that exists in the named virtual machine (or disk image). Multiple file names can be given, in which case they are concatenated together. Each file name must be a full path, starting at the root directory (starting with '/').

tux >  virt-cat -a sles.qcow2 /etc/fstab
devpts /dev/pts devpts mode=0620,gid=5 0 0
proc   /proc    proc   defaults        0 0

17.3.5.4 virt-df

virt-df is a command line tool to display free space on virtual machine file systems. Unlike other tools, it does not only display the size of disk allocated to a virtual machine, but can look inside disk images to show how much space is actually being used.

tux >  virt-df -a sles.qcow2
Filesystem                           1K-blocks       Used  Available  Use%
sles.qcow2:/dev/sda1                  16381864     520564   15022492  4%

17.3.5.5 virt-edit

virt-edit is a command line tool capable of editing files that reside in the named virtual machine (or disk image).

17.3.5.6 virt-tar-in/out

virt-tar-in unpacks an uncompressed TAR archive into a virtual machine disk image or named libvirt domain. virt-tar-out packs a virtual machine disk image directory into a TAR archive.

tux >  virt-tar-out -a sles.qcow2 /home homes.tar

17.3.5.7 virt-copy-in/out

virt-copy-in copies files and directories from the local disk into a virtual machine disk image or named libvirt domain. virt-copy-out copies files and directories out of a virtual machine disk image or named libvirt domain.

tux >  virt-copy-in -a sles.qcow2 data.tar /tmp/
virt-ls -a sles.qcow2 /tmp/
.ICE-unix
.X11-unix
data.tar

17.3.5.8 virt-log

virt-log shows the log files of the named libvirt domain, virtual machine or disk image. If the package guestfs-winsupport is installed it can also show the event log of a Windows virtual machine disk image.

tux >  virt-log -a windows8.qcow2
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Events>
<Event xmlns="http://schemas.microsoft.com/win/2004/08/events/event"><System><Provider Name="EventLog"></Provider>
<EventID Qualifiers="32768">6011</EventID>
<Level>4</Level>
<Task>0</Task>
<Keywords>0x0080000000000000</Keywords>
<TimeCreated SystemTime="2014-09-12 05:47:21"></TimeCreated>
<EventRecordID>1</EventRecordID>
<Channel>System</Channel>
<Computer>windows-uj49s6b</Computer>
<Security UserID=""></Security>
</System>
<EventData><Data><string>WINDOWS-UJ49S6B</string>
<string>WIN-KG190623QG4</string>
</Data>
<Binary></Binary>
</EventData>
</Event>

...

17.3.6 guestfish

guestfish is a shell and command line tool for examining and modifying virtual machine file systems. It uses libguestfs and exposes all of the functionality of the guestfs API.

Examples of usage:

tux >  guestfish -a disk.img <<EOF
run
list-filesystems
EOF
guestfish

Welcome to guestfish, the guest filesystem shell for
editing virtual machine filesystems and disk images.

Type: 'help' for help on commands
      'man' to read the manual
      'quit' to quit the shell

><fs> add sles.qcow2
><fs> run
><fs> list-filesystems
/dev/sda1: ext3
><fs> mount /dev/sda1 /
 cat /etc/fstab
devpts  /dev/pts          devpts  mode=0620,gid=5 0 0
proc    /proc             proc    defaults        0 0
sysfs   /sys              sysfs   noauto          0 0
debugfs /sys/kernel/debug debugfs noauto          0 0
usbfs   /proc/bus/usb     usbfs   noauto          0 0
tmpfs   /run              tmpfs   noauto          0 0
/dev/disk/by-id/ata-QEMU_HARDDISK_QM00001-part1 / ext3 defaults 1 1

17.3.7 Converting a Physical Machine into a KVM Guest

Libguestfs provides tools to help converting Xen virtual machines or physical machines into KVM guests. The Xen to KVM conversion scenario is covered by the Xen to KVM Migration Guide. The following section will cover a special use case: converting a bare metal machine into a KVM one.

Converting a physical machine into a KVM one is not yet supported in SUSE Linux Enterprise Server. This feature is released as a technology preview only.

Converting a physical machine requires collecting information about it and transmitting this to a conversion server. This is achieved by running a live system prepared with virt-p2v and kiwi tools on the machine.

Procedure 17.2: Using virt-p2v
  1. Install the needed packages with the command:

    root # zypper in virt-p2v kiwi-desc-isoboot
    Note
    Note

    These steps will document how to create an ISO image to create a bootable DVD. Alternatively, you can create a PXE boot image instead; for more information about building PXE images with KIWI, see man virt-p2v-make-kiwi.

  2. Create a KIWI configuration:

    tux > virt-p2v-make-kiwi -o /tmp/p2v.kiwi

    The -o defines where to create the KIWI configuration.

  3. Edit the config.xml file in the generated configuration if needed. For example, in config.xml adjust the keyboard layout of the live system.

  4. Build the ISO image with kiwi:

    tux >  kiwi --build /tmp/p2v.kiwi1 \
         -d /tmp/build2 \
         --ignore-repos \
         --add-repo http://URL/TO/SLE/REPOSITORIES3 \
         --type iso

    1

    The directory where the KIWI configuration was generated in the previous step.

    2

    The directory where KIWI will place the generated ISO image and other intermediary build results.

    3

    The URLs to the package repositories as found with zypper lr -d.

    Use one --add-repo parameter per repository.

  5. Burn the ISO on a DVD or a USB stick. With such a medium, boot the machine to be converted.

  6. After the system is started, you will be asked for the connection details of the conversion server. This server is a machine with the virt-v2v package installed.

    If the network setup is more complex than a DHCP client, click the Configure network button to open the YaST network configuration dialog.

    Click the Test connection button to allow moving to the next page of the wizard.

  7. Select the disks and network interfaces to be converted and define the VM data like the amount of allocated CPUs, memory and the Virtual Machine name.

    Note
    Note

    If not defined, the created disk image format will be raw by default. This can be changed by entering the desired format in the Output format field.

    There are two possibilities to generate the virtual machine: either using the local or the libvirt output. The first one will place the Virtual Machine disk image and configuration in the path defined in the Output storage field. These can then be used to define a new libvirt-handled guest using virsh. The second method will create a new libvirt-handled guest with the disk image placed in the pool defined in the Output storage field.

    Click Start conversion to start it.

17.4 Troubleshooting

17.4.1 Btrfs-related Problems

When using the guestfs tools on an image with Btrfs root partition (the default with SUSE Linux Enterprise Server) the following error message may be displayed:

tux > virt-ls -a /path/to/sles12sp2.qcow2 /
virt-ls: multi-boot operating systems are not supported

If using guestfish '-i' option, remove this option and instead
use the commands 'run' followed by 'list-filesystems'.
You can then mount filesystems you want by hand using the
'mount' or 'mount-ro' command.

If using guestmount '-i', remove this option and choose the
filesystem(s) you want to see by manually adding '-m' option(s).
Use 'virt-filesystems' to see what filesystems are available.

If using other virt tools, multi-boot operating systems won't work
with these tools.  Use the guestfish equivalent commands
(see the virt tool manual page).

This is usually caused by the presence of snapshots in the guests. In this case guestfs does not know which snapshot to bootstrap. To force the use of a snapshot, use the -m parameter as follows:

tux > virt-ls -m /dev/sda2:/:subvol=@/.snapshots/2/snapshot -a /path/to/sles12sp2.qcow2 /

17.4.2 Environment

When troubleshooting problems within a libguestfs appliance, the environment variable LIBGUESTFS_DEBUG=1 can be used to enable debug messages. To output each command/API call in a format that is similar to guestfish commands, use the environment variable LIBGUESTFS_TRACE=1.

17.4.3 libguestfs-test-tool

libguestfs-test-tool is a test program that checks if basic libguestfs functionality is working. It will print a large amount of diagnostic messages and details of the guestfs environment, then create a test image and try to start it. If it runs to completion successfully, the following message should be seen near the end:

===== TEST FINISHED OK =====

17.5 External References

Part IV Managing Virtual Machines with Xen

18 Setting Up a Virtual Machine Host

This section documents how to set up and use SUSE Linux Enterprise Server 12 SP3 as a virtual machine host.

19 Virtual Networking

A VM Guest system needs some means to communicate either with other VM Guest systems or with a local network. The network interface to the VM Guest system is made of a split device driver, which means that any virtual Ethernet device has a corresponding network interface in Dom0. This interface is s…

20 Managing a Virtualization Environment

Apart from using the recommended libvirt library (Part II, “Managing Virtual Machines with libvirt), you can manage Xen guest domains with the xl tool from the command line.

21 Block Devices in Xen

22 Virtualization: Configuration Options and Settings

The documentation in this section, describes advanced management tasks and configuration options that might help technology innovators implement leading-edge virtualization solutions. It is provided as a courtesy and does not imply that all documented options and tasks are supported by Novell, Inc.

23 Administrative Tasks

24 XenStore: Configuration Database Shared between Domains

This section introduces basic information about XenStore, its role in the Xen environment, the directory structure of files used by XenStore, and the description of XenStore's commands.

25 Xen as a High-Availability Virtualization Host

Setting up two Xen hosts as a failover system has several advantages compared to a setup where every server runs on dedicated hardware.

18 Setting Up a Virtual Machine Host

  • Filename: xen_virtualization_vhost.xml
  • ID: cha.xen.vhost

This section documents how to set up and use SUSE Linux Enterprise Server 12 SP3 as a virtual machine host.

Usually, the hardware requirements for the Dom0 are the same as those for the SUSE Linux Enterprise Server operating system. Additional CPU, disk, memory, and network resources should be added to accommodate the resource demands of all planned VM Guest systems.

Tip
Tip: Resources

Remember that VM Guest systems, like physical machines, perform better when they run on faster processors and have access to more system memory.

The virtual machine host requires several software packages and their dependencies to be installed. To install all necessary packages, run YaST Software Management, select View › Patterns and choose Xen Virtual Machine Host Server for installation. The installation can also be performed with YaST using the module Virtualization › Install Hypervisor and Tools.

After the Xen software is installed, restart the computer and, on the boot screen, choose the newly added option with the Xen kernel.

Updates are available through your update channel. To be sure to have the latest updates installed, run YaST Online Update after the installation has finished.

18.1 Best Practices and Suggestions

When installing and configuring the SUSE Linux Enterprise Server operating system on the host, be aware of the following best practices and suggestions:

  • If the host should always run as Xen host, run YaST System › Boot Loader and activate the Xen boot entry as default boot section.

    • In YaST, click System > Boot Loader.

    • Change the default boot to the Xen label, then click Set as Default.

    • Click Finish.

  • For best performance, only the applications and processes required for virtualization should be installed on the virtual machine host.

  • When using both iSCSI and OCFS2 to host Xen images, the latency required for OCFS2 default timeouts in SUSE Linux Enterprise Server may not be met. To reconfigure this timeout, run systemctl configure o2cb or edit O2CB_HEARTBEAT_THRESHOLD in the system configuration.

  • If you intend to use a watchdog device attached to the Xen host, use only one at a time. It is recommended to use a driver with actual hardware integration over a generic software one.

Note
Note: Hardware Monitoring

The Dom0 kernel is running virtualized, so tools like irqbalance or lscpu will not reflect the real hardware characteristics.

18.2 Managing Dom0 Memory

When the host is set up, a percentage of system memory is reserved for the hypervisor, and all remaining memory is automatically allocated to Dom0.

A better solution is to set a default amount of memory for Dom0, so the memory can be allocated appropriately to the hypervisor. An adequate amount would be 20 percent of the total system memory up to 4 GiB. A recommended minimum amount would be 512 MiB

Warning
Warning: Minimum amount of Memory

The minimum amount of memory heavily depends on how many VM Guest(s) the host should handle. So be sure you have enough memory to support all your VM Guests. If the value is too low, the host system may hang when multiple VM Guests use most of the memory.

18.2.1 Setting a Maximum Amount of Memory

  1. Determine the amount of memory to set for Dom0.

  2. At Dom0, type xl info to view the amount of memory that is available on the machine. The memory that is currently allocated by Dom0 can be determined with the command xl list.

  3. Run YaST › Boot Loader.

  4. Select the Xen section.

  5. In Additional Xen Hypervisor Parameters, add dom0_mem=MEM_AMOUNT where MEM_AMOUNT is the maximum amount of memory to allocate to Dom0. Add K, M, or G, to specify the size, for example, dom0_mem=768M.

  6. Restart the computer to apply the changes.

Warning
Warning: Xen Dom0 Memory

When using the XL tool stack and the dom0_mem= option for the Xen hypervisor in GRUB 2 you need to disable xl autoballoon in etc/xen/xl.conf. Otherwise launching VMs will fail with errors about not being able to balloon down Dom0. So add autoballoon=0 to xl.conf if you have the dom0_mem= option specified for Xen. Also see Xen dom0 memory

18.3 Network Card in Fully Virtualized Guests

In a fully virtualized guest, the default network card is an emulated Realtek network card. However, it also possible to use the split network driver to run the communication between Dom0 and a VM Guest. By default, both interfaces are presented to the VM Guest, because the drivers of some operating systems require both to be present.

When using SUSE Linux Enterprise Server, only the paravirtualized network cards are available for the VM Guest by default. The following network options are available:

emulated

To use an emulated network interface like an emulated Realtek card, specify type=ioemu in the vif device section of the domain xl configuration. An example configuration would look like:

vif = [ 'type=ioemu,mac=00:16:3e:5f:48:e4,bridge=br0' ]

Find more details about the xl configuration in the xl.conf manual page man 5 xl.conf.

paravirtualized

When you specify type=vif and do not specify a model or type, the paravirtualized network interface is used:

vif = [ 'type=vif,mac=00:16:3e:5f:48:e4,bridge=br0,backen=0' ]
emulated and paravirtualized

If the administrator should be offered both options, simply specify both type and model. The xl configuration would look like:

vif = [ 'type=ioemu,mac=00:16:3e:5f:48:e4,model=rtl8139,bridge=br0' ]

In this case, one of the network interfaces should be disabled on the VM Guest.

18.4 Starting the Virtual Machine Host

If virtualization software is correctly installed, the computer boots to display the GRUB 2 boot loader with a Xen option on the menu. Select this option to start the virtual machine host.

Note
Note: Xen and Kdump

In Xen, the hypervisor manages the memory resource. If you need to reserve system memory for a recovery kernel in Dom0, this memory need to be reserved by the hypervisor. Thus, it is necessary to add the parameter crashkernel=size to the kernel line instead of using the line with the other boot options.

For more information on the crashkernel parameter, see Section 17.4, “Calculating crashkernel Allocation Size”.

If the Xen option is not on the GRUB 2 menu, review the steps for installation and verify that the GRUB 2 boot loader has been updated. If the installation has been done without selecting the Xen pattern, run the YaST Software Management, select the filter Patterns and choose Xen Virtual Machine Host Server for installation.

After booting the hypervisor, the Dom0 virtual machine starts and displays its graphical desktop environment. If you did not install a graphical desktop, the command line environment appears.

Tip
Tip: Graphics Problems

Sometimes it may happen that the graphics system does not work properly. In this case, add vga=ask to the boot parameters. To activate permanent settings, use vga=mode-0x??? where ??? is calculated as 0x100 + VESA mode from http://en.wikipedia.org/wiki/VESA_BIOS_Extensions, for example vga=mode-0x361.

Before starting to install virtual guests, make sure that the system time is correct. To do this, configure NTP (Network Time Protocol) on the controlling domain:

  1. In YaST select Network Services › NTP Configuration.

  2. Select the option to automatically start the NTP daemon during boot. Provide the IP address of an existing NTP time server, then click Finish.

Note
Note: Time Services on Virtual Guests

Hardware clocks commonly are not very precise. All modern operating systems try to correct the system time compared to the hardware time by means of an additional time source. To get the correct time on all VM Guest systems, also activate the network time services on each respective guest or make sure that the guest uses the system time of the host. For more about Independent Wallclocks in SUSE Linux Enterprise Server see Section 16.2, “Xen Virtual Machine Clock Settings”.

For more information about managing virtual machines, see Chapter 20, Managing a Virtualization Environment.

18.5 PCI Pass-Through

To take full advantage of VM Guest systems, it is sometimes necessary to assign specific PCI devices to a dedicated domain. When using fully virtualized guests, this functionality is only available if the chipset of the system supports this feature, and if it is activated from the BIOS.

This feature is available from both AMD* and Intel*. For AMD machines, the feature is called IOMMU; in Intel speak, this is VT-d. Note that Intel-VT technology is not sufficient to use this feature for fully virtualized guests. To make sure that your computer supports this feature, ask your supplier specifically to deliver a system that supports PCI Pass-Through.

Limitations
  • Some graphics drivers use highly optimized ways to access DMA. This is not supported, and thus using graphics cards may be difficult.

  • When accessing PCI devices behind a PCIe bridge, all of the PCI devices must be assigned to a single guest. This limitation does not apply to PCIe devices.

  • Guests with dedicated PCI devices cannot be migrated live to a different host.

The configuration of PCI Pass-Through is twofold. First, the hypervisor must be informed at boot time that a PCI device should be available for reassigning. Second, the PCI device must be assigned to the VM Guest.

18.5.1 Configuring the Hypervisor for PCI Pass-Through

  1. Select a device to reassign to a VM Guest. To do this, run lspci and read the device number. For example, if lspci contains the following line:

    06:01.0 Ethernet controller: Digital Equipment Corporation DECchip 21142/43 (rev 41)

    In this case, the PCI number is (06:01.0).

  2. Specify a module dependency to ensure that xen_pciback is the first module to control the device. Add the file named /etc/modprobe.d/50-e1000e.conf with the following content:

    install e1000e /sbin/modprobe xen_pciback ; /sbin/modprobe \
     --first-time --ignore-install e1000e
  3. Instruct the xen_pciback module to control the device using the 'hide' option. Edit or create /etc/modprobe.d/50-xen-pciback.conf with the following content:

    options xen_pciback hide=(06:01.0)
  4. Reboot the system.

  5. Check if the device is in the list of assignable devices with the command

    xl pci-assignable-list

18.5.1.1 Dynamic Assignment with xl

To avoid restarting the host system, you can use dynamic assignment with xl to use PCI Pass-Through.

Begin by making sure that dom0 has the pciback module loaded:

modprobe pciback

Then make a device assignable by using xl pci-assignable-add. For example, to make the device 06:01.0 available for guests, run the command:

xl pci-assignable-add 06:01.0

18.5.2 Assigning PCI Devices to VM Guest Systems

There are several possibilities to dedicate a PCI device to a VM Guest:

Adding the device while installing:

During installation, add the pci line to the configuration file:

pci=['06:01.0']
Hotplugging PCI devices to VM Guest systems

The command xl can be used to add or remove PCI devices on the fly. To add the device with number 06:01.0 to a guest with name sles12 use:

xl pci-attach sles12 06:01.0
Adding the PCI device to Xend

To add the device to the guest permanently, add the following snippet to the guest configuration file:

pci = [ '06:01.0,power_mgmt=1,permissive=1' ]

After assigning the PCI device to the VM Guest, the guest system must care for the configuration and device drivers for this device.

18.5.3 VGA Pass-Through

Xen 4.0 and newer supports VGA graphics adapter pass-through on fully virtualized VM Guests. The guest can take full control of the graphics adapter with high-performance full 3D and video acceleration.

Limitations
  • VGA Pass-Through functionality is similar to PCI Pass-Through and as such also requires IOMMU (or Intel VT-d) support from the mainboard chipset and BIOS.

  • Only the primary graphics adapter (the one that is used when you power on the computer) can be used with VGA Pass-Through.

  • VGA Pass-Through is supported only for fully virtualized guests. Paravirtual guests (PV) are not supported.

  • The graphics card cannot be shared between multiple VM Guests using VGA Pass-Through — you can dedicate it to one guest only.

To enable VGA Pass-Through, add the following settings to your fully virtualized guest configuration file:

gfx_passthru=1
pci=['yy:zz.n']

where yy:zz.n is the PCI controller ID of the VGA graphics adapter as found with lspci -v on Dom0.

18.5.4 Troubleshooting

In some circumstances, problems may occur during the installation of the VM Guest. This section describes some known problems and their solutions.

During boot, the system hangs

The software I/O translation buffer allocates a large chunk of low memory early in the bootstrap process. If the requests for memory exceed the size of the buffer it usually results in a hung boot process. To check if this is the case, switch to console 10 and check the output there for a message similar to

kernel: PCI-DMA: Out of SW-IOMMU space for 32768 bytes at device 000:01:02.0

In this case you need to increase the size of the swiotlb. Add swiotlb=128 on the cmdline of Dom0. Note that the number can be adjusted up or down to find the optimal size for the machine.

Note
Note: swiotlb a PV guest

The swiotlb=force kernel parameter is required for DMA access to work for PCI devices on a PV guest. For more information about IOMMU and the swiotlb option see the file boot-options.txt from the package kernel-source.

18.6 USB Pass-Through

There are two methods for passing through individual host USB devices to a guest. The first is via an emulated USB device controller, the second is using PVUSB.

18.6.1 Identify the USB Device

Before you can pass through a USB device to the VM Guest, you need to identify it on the VM Host Server. Use the lsusb command to list the USB devices on the host system:

root # lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 003: ID 0461:4d15 Primax Electronics, Ltd Dell Optical Mouse
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

To pass through the Dell mouse, for example, specify either the device tag in the form vendor_id:device_id (0461:4d15) or the bus address in the form bus.device (2.3). Remember to remove leading zeros, otherwise xl would interpret the numbers as octal values.

18.6.2 Emulated USB Device

In emulated USB, the device model (QEMU) presents an emulated USB controller to the guest. The USB device is then controlled from Dom0 while USB commands are translated between the VM Guest and the host USB device. This method is only available to fully virtualized domains (HVM).

Enable the emulated USB hub with the usb=1 option. Then specify devices among the list of devices in the config file along with other emulated devices by using host:USBID. For example:

usb=1
usbdevice=['tablet','host:2.3','host:0424:460']

18.6.3 Pravirtualized PVUSB

PVUSB is a new high performance method for USB Pass-Through from dom0 to the virtualized guests. PVUSB supports both USB 2.0 and USB 1.1 devices. PVUSB uses a paravirtualized front-end and back-end interfaces. With PVUSB, there are two ways to add USB devices to a guest:

  • via the configuration file at domain creation time

  • via hotplug while the VM is running

PVUSB uses a paravirtualized front- and back-end interface. PVUSB supports USB 1.1 and USB 2.0, and it works for both PV and HVM guests. To use PVUSB, you need usbfront in your guest OS, and usbback in dom0 or usb back-end in qemu. On SUSE Linux Enterprise Server, the usb back-end comes with qemu.

As of Xen 4.7, xl PVUSB support and hotplug support is introduced.

In the configuration file, specify USB controllers and USB host devices with usbctrl and usbdev. For example, in case of HVM guests:

usbctrl=['type=qusb,version=2,ports=4', 'type=qusb,version=1,ports=4', ]
usbdev=['hostbus=2, hostaddr=1, controller=0,port=1', ]
Note
Note

It is important to specify type=qusb for the controller of HVM guests.

To manage hotpluggin PVUSB devices, use the usbctrl-attach, usbctrl-detach, usb-list, usbdev-attach and usb-detach subcommands. For example:

Create a USB controller which is version USB 1.1 and has 8 ports:

root # xl usbctrl-attach test_vm version=1 ports=8 type=qusb

Find the first available controller:port in the domain, and attach USB device whose busnum:devnum is 2:3 to it; you can also specify controller and port:

root # xl usbdev-attach test_vm hostbus=2 hostaddr=3

Show all USB controllers and USB devices in the domain:

root # xl usb-list test_vm
Devid  Type   BE  state usb-ver ports
0      qusb   0   1     1       8
  Port 1: Bus 002 Device 003
  Port 2:
  Port 3:
  Port 4:
  Port 5:
  Port 6:
  Port 7:
  Port 8:

Detach the USB device under controller 0 port 1:

root # xl usbdev-detach test_vm 0 1

Remove the USB controller with the indicated dev_id, and all USB devices under it:

root # xl usbctrl-detach test_vm dev_id

For more information, see https://wiki.xenproject.org/wiki/Xen_USB_Passthrough.

19 Virtual Networking

  • Filename: xen_host_network.xml
  • ID: cha.xen.network

A VM Guest system needs some means to communicate either with other VM Guest systems or with a local network. The network interface to the VM Guest system is made of a split device driver, which means that any virtual Ethernet device has a corresponding network interface in Dom0. This interface is set up to access a virtual network that is run in Dom0. The bridged virtual network is fully integrated into the system configuration of SUSE Linux Enterprise Server and can be configured with YaST.

When installing a Xen VM Host Server, a bridged network configuration will be proposed during normal network configuration. The user can choose to change the configuration during the installation and customize it to the local needs.

If desired, Xen VM Host Server can be installed after performing a default Physical Server installation using the Install Hypervisor and Tools module in YaST. This module will prepare the system for hosting virtual machines, including invocation of the default bridge networking proposal.

In case the necessary packages for a Xen VM Host Server are installed manually with rpm or zypper, the remaining system configuration needs to be done by the administrator manually or with YaST.

The network scripts that are provided by Xen are not used by default in SUSE Linux Enterprise Server. They are only delivered for reference but disabled. The network configuration that is used in SUSE Linux Enterprise Server is done by means of the YaST system configuration similar to the configuration of network interfaces in SUSE Linux Enterprise Server.

For more general information about managing network bridges, see Section 13.2, “Bridged Networking”.

19.1 Network Devices for Guest Systems

The Xen hypervisor can provide different types of network interfaces to the VM Guest systems. The preferred network device should be a paravirtualized network interface. This yields the highest transfer rates with the lowest system requirements. Up to eight network interfaces may be provided for each VM Guest.

Systems that are not aware of paravirtualized hardware may not have this option. To connect systems to a network that can only run fully virtualized, several emulated network interfaces are available. The following emulations are at your disposal:

  • Realtek 8139 (PCI). This is the default emulated network card.

  • AMD PCnet32 (PCI)

  • NE2000 (PCI)

  • NE2000 (ISA)

  • Intel e100 (PCI)

  • Intel e1000 and its variants e1000-82540em, e1000-82544gc, e1000-82545em (PCI)

All these network interfaces are software interfaces. Because every network interface must have a unique MAC address, an address range has been assigned to Xensource that can be used by these interfaces.

Tip
Tip: Virtual Network Interfaces and MAC Addresses

The default configuration of MAC addresses in virtualized environments creates a random MAC address that looks like 00:16:3E:xx:xx:xx. Normally, the amount of available MAC addresses should be big enough to get only unique addresses. However, if you have a very big installation, or to make sure that no problems arise from random MAC address assignment, you can also manually assign these addresses.

For debugging or system management purposes, it may be useful to know which virtual interface in Dom0 is connected to which Ethernet device in a running guest. This information may be read from the device naming in Dom0. All virtual devices follow the rule vif<domain number>.<interface_number>.

For example, if you want to know the device name for the third interface (eth2) of the VM Guest with id 5, the device in Dom0 would be vif5.2. To obtain a list of all available interfaces, run the command ip a.

The device naming does not contain any information about which bridge this interface is connected to. However, this information is available in Dom0. To get an overview about which interface is connected to which bridge, run the command brctl show. The output may look like the following:

# brctl show
bridge name     bridge id               STP enabled     interfaces
br0             8000.001cc0309083       no              eth0
                                                        vif2.1
br1             8000.000476f060cc       no              eth1
                                                        vif2.0
br2             8000.000000000000       no

In this example, there are three configured bridges: br0, br1 and br2. Currently, br0 and br1 each have a real Ethernet device added: eth0 and eth1, respectively. There is one VM Guest running with the ID 2 that has two Ethernet devices available. eth0 on the VM Guest is bridged with eth1 on the VM Host Server and eth1 on the VM Guest is connected to eth0 on the VM Host Server. The third bridge with the name br2 is not connected to any VM Guest nor any real Ethernet device.

19.2 Host-Based Routing in Xen

Xen can be set up to use host-based routing in the controlling Dom0. Unfortunately, this is not yet well supported from YaST and requires quite an amount of manual editing of configuration files. Thus, this is a task that requires an advanced administrator.

The following configuration will only work when using fixed IP addresses. Using DHCP is not practicable with this procedure, because the IP address must be known to both, the VM Guest and the VM Host Server system.

The easiest way to create a routed guest is to change the networking from a bridged to a routed network. As a requirement to the following procedures, a VM Guest with a bridged network setup must be installed. For example, the VM Host Server is named earth with the IP 192.168.1.20, and the VM Guest has the name alice with the IP 192.168.1.21.

Procedure 19.1: Configuring a routed IPv4 VM Guest
  1. Make sure that alice is shut down. Use xl commands to shut down and check.

  2. Prepare the network configuration on the VM Host Server earth:

    1. Create a hotplug interface that will be used to route the traffic. To accomplish this, create a file named /etc/sysconfig/network/ifcfg-alice.0 with the following content:

      NAME="Xen guest alice"
      BOOTPROTO="static"
      STARTMODE="hotplug"
    2. Edit the file /etc/sysconfig/SuSEfirewall2 and add the following configurations:

      • Add alice.0 to the devices in FW_DEV_EXT:

        FW_DEV_EXT="br0 alice.0"
      • Switch on the routing in the firewall:

        FW_ROUTE="yes"
      • Tell the firewall which address should be forwarded:

        FW_FORWARD="192.168.1.21/32,0/0"
      • Finally, restart the firewall with the command:

        sudo systemctl restart SuSEfirewall2
    3. Add a static route to the interface of alice. To accomplish this, add the following line to the end of /etc/sysconfig/network/routes:

      192.168.1.21  -  -  alice.0
    4. To make sure that the switches and routers that the VM Host Server is connected to know about the routed interface, activate proxy_arp on earth. Add the following lines to /etc/sysctl.conf:

      net.ipv4.conf.default.proxy_arp = 1
      net.ipv4.conf.all.proxy_arp = 1
    5. Activate all changes with the commands:

      sudo systemctl restart systemd-sysctl wicked
  3. Proceed with configuring the Xen configuration of the VM Guest by changing the vif interface configuration for alice as described in Section 20.1, “XL—Xen Management Tool”. Make the following changes to the text file you generate during the process:

    1. Remove the snippet

      bridge=br0
    2. And add the following one:

      vifname=vifalice.0

      or

      vifname=vifalice.0=emu

      for a fully virtualized domain.

    3. Change the script that is used to set up the interface to the following:

      script=/etc/xen/scripts/vif-route-ifup
    4. Activate the new configuration and start the VM Guest.

  4. The remaining configuration tasks must be accomplished from inside the VM Guest.

    1. Open a console to the VM Guest with xl console DOMAIN and log in.

    2. Check that the guest IP is set to 192.168.1.21.

    3. Provide VM Guest with a host route and a default gateway to the VM Host Server. Do this by adding the following lines to /etc/sysconfig/network/routes:

      192.168.1.20 - - eth0
      default 192.168.1.20 - -
  5. Finally, test the network connection from the VM Guest to the world outside and from the network to your VM Guest.

19.3 Creating a Masqueraded Network Setup

Creating a masqueraded network setup is quite similar to the routed setup. However, there is no proxy_arp needed, and some firewall rules are different. To create a masqueraded network to a guest dolly with the IP address 192.168.100.1 where the host has its external interface on br0, proceed as follows. For easier configuration, only the already installed guest is modified to use a masqueraded network:

Procedure 19.2: Configuring a masqueraded IPv4 VM Guest
  1. Shut down the VM Guest system with xl shutdown DOMAIN.

  2. Prepare the network configuration on the VM Host Server:

    1. Create a hotplug interface that will be used to route the traffic. To accomplish this, create a file named /etc/sysconfig/network/ifcfg-dolly.0 with the following content:

      NAME="Xen guest dolly"
      BOOTPROTO="static"
      STARTMODE="hotplug"
    2. Edit the file /etc/sysconfig/SuSEfirewall2 and add the following configurations:

      • Add dolly.0 to the devices in FW_DEV_DMZ:

        FW_DEV_DMZ="dolly.0"
      • Switch on the routing in the firewall:

        FW_ROUTE="yes"
      • Switch on masquerading in the firewall:

        FW_MASQUERADE="yes"
      • Tell the firewall which network should be masqueraded:

        FW_MASQ_NETS="192.168.100.1/32"
      • Remove the networks from the masquerading exceptions:

        FW_NOMASQ_NETS=""
      • Finally, restart the firewall with the command:

        sudo systemctl restart SuSEfirewall2
    3. Add a static route to the interface of dolly. To accomplish this, add the following line to the end of /etc/sysconfig/network/routes:

      192.168.100.1 - - dolly.0
    4. Activate all changes with the command:

      sudo systemctl restart wicked
  3. Proceed with configuring the Xen configuration of the VM Guest.

    1. Change the vif interface configuration for dolly as described in Section 20.1, “XL—Xen Management Tool”.

    2. Remove the entry:

      bridge=br0
    3. And add the following one:

      vifname=vifdolly.0
    4. Change the script that is used to set up the interface to the following:

      script=/etc/xen/scripts/vif-route-ifup
    5. Activate the new configuration and start the VM Guest.

  4. The remaining configuration tasks need to be accomplished from inside the VM Guest.

    1. Open a console to the VM Guest with xl console DOMAIN and log in.

    2. Check whether the guest IP is set to 192.168.100.1.

    3. Provide VM Guest with a host route and a default gateway to the VM Host Server. Do this by adding the following lines to /etc/sysconfig/network/routes:

      192.168.1.20 - - eth0
      default 192.168.1.20 - -
  5. Finally, test the network connection from the VM Guest to the outside world.

19.4 Special Configurations

There are many network configuration possibilities available to Xen. The following configurations are not activated by default:

19.4.1 Bandwidth Throttling in Virtual Networks

With Xen, you may limit the network transfer rate a virtual guest may use to access a bridge. To configure this, you need to modify the VM Guest configuration as described in Section 20.1, “XL—Xen Management Tool”.

In the configuration file, first search for the device that is connected to the virtual bridge. The configuration looks like the following:

vif = [ 'mac=00:16:3e:4f:94:a9,bridge=br0' ]

To add a maximum transfer rate, add a parameter rate to this configuration as in:

vif = [ 'mac=00:16:3e:4f:94:a9,bridge=br0,rate=100Mb/s' ]

Note that the rate is either Mb/s (megabits per second) or MB/s (megabytes per second). In the above example, the maximum transfer rate of the virtual interface is 100 megabits. By default, there is no limitation to the bandwidth of a guest to the virtual bridge.

It is even possible to fine-tune the behavior by specifying the time window that is used to define the granularity of the credit replenishment:

vif = [ 'mac=00:16:3e:4f:94:a9,bridge=br0,rate=100Mb/s@20ms' ]

19.4.2 Monitoring the Network Traffic

To monitor the traffic on a specific interface, the little application iftop is a nice program that displays the current network traffic in a terminal.

When running a Xen VM Host Server, you need to define the interface that is monitored. The interface that Dom0 uses to get access to the physical network is the bridge device, for example br0. This, however, may vary on your system. To monitor all traffic to the physical interface, run a terminal as root and use the command:

iftop -i br0

To monitor the network traffic of a special network interface of a specific VM Guest, supply the correct virtual interface. For example, to monitor the first Ethernet device of the domain with id 5, use the command:

ftop -i vif5.0

To quit iftop, press the key Q. More options and possibilities are available in the manual page man 8 iftop.

20 Managing a Virtualization Environment

  • Filename: xen_virtualization_manage.xml
  • ID: cha.xen.manage

Apart from using the recommended libvirt library (Part II, “Managing Virtual Machines with libvirt), you can manage Xen guest domains with the xl tool from the command line.

20.1 XL—Xen Management Tool

The xl program is a tool for managing Xen guest domains. It is part of the xen-tools package. xl is based on the LibXenlight library, and can be used for general domain management, such as domain creation, listing, pausing, or shutting down. Usually you need to be root to execute xl commands.

Note
Note

xl can only manage running guest domains specified by their configuration file. If a guest domain is not running, you cannot manage it with xl.

Tip
Tip

To allow users to continue to have managed guest domains in the way the obsolete xm command allowed, we now recommend using libvirt's virsh and virt-manager tools. For more information, see Part II, “Managing Virtual Machines with libvirt.

xl operations rely upon xenstored and xenconsoled services. Make sure you start

systemctl start xencommons

at boot time to initialize all the daemons required by xl.

Tip
Tip: Set up a xenbr0 Network Bridge in the Host Domain

In the most common network configuration, you need to set up a bridge in the host domain named xenbr0 to have a working network for the guest domains.

The basic structure of every xl command is:

xl <subcommand> [options] domain_id

where <subcommand> is the xl command to run, domain_id is the ID number assigned to a domain or the name of the virtual machine, and OPTIONS indicates subcommand-specific options.

For a complete list of the available xl subcommands, run xl help. For each command, there is a more detailed help available that is obtained with the extra parameter --help. More information about the respective subcommands is available in the manual page of xl.

For example, the xl list --help displays all options that are available to the list command. As an example, the xl list command displays the status of all virtual machines.

# xl list
Name                                 ID    Mem VCPUs        State   Time(s)
Domain-0                              0    457     2       r-----   2712.9
sles12                                7    512     1       -b----     16.3
opensuse                                   512     1                  12.9

The State information indicates if a machine is running, and in which state it is. The most common flags are r (running) and b (blocked) where blocked means it is either waiting for IO, or sleeping because there is nothing to do. For more details about the state flags, see man 1 xl.

Other useful xl commands include:

  • xl create creates a virtual machine from a given configuration file.

  • xl reboot reboots a virtual machine.

  • xl destroy immediately terminates a virtual machine.

  • xl block-list displays all virtual block devices attached to a virtual machine.

20.1.1 Guest Domain Configuration File

When operating domains, xl requires a domain configuration file for each domain. The default directory to store such configuration files is /etc/xen/.

A domain configuration file is a plain text file. It consists of several KEY=VALUE pairs. Some keys are mandatory, some are general and apply to any guest, and some apply only to a specific guest type (para or fully virtualized). A value can either be a "string" surrounded by single or double quotes, a number, a boolean value, or a list of several values enclosed in brackets [ value1, value2, ... ].

Example 20.1: Guest Domain Configuration File: /etc/xen/sled12.cfg
name= "sled12"
builder = "hvm"
vncviewer = 1
memory = 512
disk = [ '/var/lib/xen/images/sled12.raw,,hda', '/dev/cdrom,,hdc,cdrom' ]
vif = [ 'mac=00:16:3e:5f:48:e4,model=rtl8139,bridge=br0' ]
boot = "n"

To start such domain, run xl create /etc/xen/sled12.cfg.

20.2 Automatic Start of Guest Domains

To make a guest domain start automatically after the host system boots, follow these steps:

  1. Create the domain configuration file if it does not exist, and save it in the /etc/xen/ directory, for example /etc/xen/domain_name.cfg.

  2. Make a symbolic link of the guest domain configuration file in the auto/ subdirectory.

    ln -s /etc/xen/domain_name.cfg /etc/xen/auto/domain_name.cfg
  3. On the next system boot, the guest domain defined in domain_name.cfg will be started.

20.3 Event Actions

In the guest domain configuration file, you can define actions to be performed on a predefined set of events. For example, to tell the domain to restart itself after it is powered off, include the following line in its configuration file:

on_poweroff="restart"

A list of predefined events for a guest domain follows:

List of Events
on_poweroff

Specifies what should be done with the domain if it shuts itself down.

on_reboot

Action to take if the domain shuts down with a reason code requesting a reboot.

on_watchdog

Action to take if the domain shuts down because of a Xen watchdog timeout.

on_crash

Action to take if the domain crashes.

For these events, you can define one of the following actions:

List of Related Actions
destroy

Destroy the domain.

restart

Destroy the domain and immediately create a new domain with the same configuration.

rename-restart

Rename the domain that terminated, and then immediately create a new domain with the same configuration as the original.

preserve

Keep the domain. It can be examined, and later destroyed with xl destroy.

coredump-destroy

Write a core dump of the domain to /var/xen/dump/NAME and then destroy the domain.

coredump-restart

Write a core dump of the domain to /var/xen/dump/NAME and then restart the domain.

20.4 Time Stamp Counter

The Time Stamp Counter (TSC) may be specified for each domain in the guest domain configuration file (for more information, see Section 20.1.1, “Guest Domain Configuration File”).

With the tsc_mode setting, you specify whether rdtsc instructions are executed natively (fast, but TSC-sensitive applications may sometimes run incorrectly) or emulated (always run correctly, but performance may suffer).

tsc_mode=0 (default)

Use this to ensure correctness while providing the best performance possible—for more information, see https://xenbits.xen.org/docs/4.3-testing/misc/tscmode.txt.

tsc_mode=1 (always emulate)

Use this when TSC-sensitive apps are running and worst-case performance degradation is known and acceptable.

tsc_mode=2 (never emulate)

Use this when all applications running in this VM are TSC-resilient and highest performance is required.

tsc_mode=3 (PVRDTSCP)

High-TSC-frequency applications may be paravirtualized (modified) to obtain both correctness and highest performance—any unmodified applications must be TSC-resilient.

For background information, see https://xenbits.xen.org/docs/4.3-testing/misc/tscmode.txt.

20.5 Saving Virtual Machines

Procedure 20.1: Save a Virtual Machine’s Current State
  1. Make sure the virtual machine to be saved is running.

  2. In the host environment, enter

    xl save ID STATE-FILE

    where ID is the virtual machine ID you want to save, and STATE-FILE is the name you specify for the memory state file. By default, the domain will no longer be running after you create its snapshot. Use -c to keep it running even after you create the snapshot.

20.6 Restoring Virtual Machines

Procedure 20.2: Restore a Virtual Machine’s Current State
  1. Make sure the virtual machine to be restored has not been started since you ran the save operation.

  2. In the host environment, enter

    xl restore STATE-FILE

    where STATE-FILE is the previously saved memory state file. By default, the domain will be running after it is restored. To pause it after the restore, use -p.

20.7 Virtual Machine States

A virtual machine’s state can be displayed by viewing the results of the xl list command, which abbreviates the state using a single character.

  • r - running - The virtual machine is currently running and consuming allocated resources.

  • b - blocked - The virtual machine’s processor is not running and not able to run. It is either waiting for I/O or has stopped working.

  • p - paused - The virtual machine is paused. It does not interact with the hypervisor but still maintains its allocated resources, such as memory.

  • s - shutdown - The guest operating system is in the process of being shut down, rebooted, or suspended, and the virtual machine is being stopped.

  • c - crashed - The virtual machine has crashed and is not running.

  • d - dying - The virtual machine is in the process of shutting down or crashing.

21 Block Devices in Xen

  • Filename: xen_block_devices.xml
  • ID: cha.xen.vbd

21.1 Mapping Physical Storage to Virtual Disks

The disk(s) specification for a Xen domain in the domain configuration file is as straightforward as the following example:

disk = [ 'format=raw,vdev=hdc,access=ro,devtype=cdrom,target=/root/image.iso' ]

It defines a disk block device based on the /root/image.iso disk image file. The disk will be seen as hdc by the guest, with read-only (ro) access. The type of the device is cdrom with raw format.

The following example defines an identical device, but using simplified positional syntax:

disk = [ '/root/image.iso,raw,hdc,ro,cdrom' ]

You can include more disk definitions in the same line, each one separated by a comma. If a parameter is not specified, then its default value is taken:

disk = [ '/root/image.iso,raw,hdc,ro,cdrom','/dev/vg/guest-volume,,hda','...' ]
List of Parameters
target

Source block device or disk image file path.

format

The format of the image file. Default is raw.

vdev

Virtual device as seen by the guest. Supported values are hd[x], xvd[x], sd[x] etc. See /usr/share/doc/packages/xen/misc/vbd-interface.txt for more details. This parameter is mandatory.

access

Whether the block device is provided to the guest in read-only or read-write mode. Supported values are ro or r for read-only, and rw or w for read/write access. Default is ro for devtype=cdrom, and rw for other device types.

devtype

Qualifies virtual device type. Supported value is cdrom.

backendtype

The back-end implementation to use. Supported values are phy, tap, and qdisk. Normally this option should not be specified as the back-end type is automatically determined.

script

Specifies that target is not a normal host path, but rather information to be interpreted by the executable program. The specified script file is looked for in /etc/xen/scripts if it does not point to an absolute path. These scripts are normally called block-<script_name>.

For more information about specifying virtual disks, see /usr/share/doc/packages/xen/misc/xl-disk-configuration.txt.

21.2 Mapping Network Storage to Virtual Disk

Similar to mapping a local disk image (see Section 21.1, “Mapping Physical Storage to Virtual Disks”), you can map a network disk as a virtual disk as well.

The following example shows mapping of an RBD (RADOS Block Device) disk with multiple Ceph monitors and cephx authentication enabled:

disk = [ 'vdev=hdc, backendtype=qdisk, \
target=rbd:libvirt-pool/new-libvirt-image:\
id=libvirt:key=AQDsPWtW8JoXJBAAyLPQe7MhCC+JPkI3QuhaAw==:auth_supported=cephx;none:\
mon_host=137.65.135.205\\:6789;137.65.135.206\\:6789;137.65.135.207\\:6789' ]

Following is an example of an NBD (Network Block Device) disk mapping:

disk = [ 'vdev=hdc, backendtype=qdisk, target=nbd:151.155.144.82:5555' ]

21.3 File-Backed Virtual Disks and Loopback Devices

When a virtual machine is running, each of its file-backed virtual disks consumes a loopback device on the host. By default, the host allows up to 64 loopback devices to be consumed.

To simultaneously run more file-backed virtual disks on a host, you can increase the number of available loopback devices by adding the following option to the host’s /etc/modprobe.conf.local file.

options loop max_loop=x

where x is the maximum number of loopback devices to create.

Changes take effect after the module is reloaded.

Tip
Tip

Enter rmmod loop and modprobe loop to unload and reload the module. In case rmmod does not work, unmount all existing loop devices or reboot the computer.

21.4 Resizing Block Devices

While it is always possible to add new block devices to a VM Guest system, it is sometimes more desirable to increase the size of an existing block device. In case such a system modification is already planned during deployment of the VM Guest, some basic considerations should be done:

  • Use a block device that may be increased in size. LVM devices and file system images are commonly used.

  • Do not partition the device inside the VM Guest, but use the main device directly to apply the file system. For example, use /dev/xvdb directly instead of adding partitions to /dev/xvdb.

  • Make sure that the file system to be used can be resized. Sometimes, for example with Ext3, some features must be switched off to be able to resize the file system. A file system that can be resized online and mounted is XFS. Use the command xfs_growfs to resize that file system after the underlying block device has been increased in size. For more information about XFS, see man 8 xfs_growfs.

When resizing an LVM device that is assigned to a VM Guest, the new size is automatically known to the VM Guest. No further action is needed to inform the VM Guest about the new size of the block device.

When using file system images, a loop device is used to attach the image file to the guest. For more information about resizing that image and refreshing the size information for the VM Guest, see Section 23.2, “Sparse Image Files and Disk Space”.

21.5 Scripts for Managing Advanced Storage Scenarios

There are scripts that can help with managing advanced storage scenarios such as disk environments provided by dmmd (device mapper—multi disk) including LVM environments built upon a software RAID set, or a software RAID set built upon an LVM environment. These scripts are part of the xen-tools package. After installation, they can be found in /etc/xen/scripts:

  • block-dmmd

  • block-drbd-probe

  • block-npiv

The scripts allow for external commands to perform some action, or series of actions of the block devices prior to serving them up to a guest.

These scripts could formerly only be used with xl or libxl using the disk configuration syntax script=. They can now be used with libvirt by specifying the base name of the block script in the <source> element of the disk. For example:

<source dev='dmmd:md;/dev/md0;lvm;/dev/vgxen/lv-vm01'/>

22 Virtualization: Configuration Options and Settings

  • Filename: xen_config_options.xml
  • ID: cha.xen.config

The documentation in this section, describes advanced management tasks and configuration options that might help technology innovators implement leading-edge virtualization solutions. It is provided as a courtesy and does not imply that all documented options and tasks are supported by Novell, Inc.

22.1 Virtual CD Readers

Virtual CD readers can be set up when a virtual machine is created or added to an existing virtual machine. A virtual CD reader can be based on a physical CD/DVD, or based on an ISO image. Virtual CD readers work differently depending on whether they are paravirtual or fully virtual.

22.1.1 Virtual CD Readers on Paravirtual Machines

A paravirtual machine can have up to 100 block devices composed of virtual CD readers and virtual disks. On paravirtual machines, virtual CD readers present the CD as a virtual disk with read-only access. Virtual CD readers cannot be used to write data to a CD.

After you have finished accessing a CD on a paravirtual machine, it is recommended that you remove the virtual CD reader from the virtual machine.

Paravirtualized guests can use the device type devtype=cdrom. This partly emulates the behavior of a real CD reader, and allows CDs to be changed. It is even possible to use the eject command to open the tray of the CD reader.

22.1.2 Virtual CD Readers on Fully Virtual Machines

A fully virtual machine can have up to four block devices composed of virtual CD readers and virtual disks. A virtual CD reader on a fully virtual machine interacts with an inserted CD in the way you would expect a physical CD reader to interact.

When a CD is inserted in the physical CD reader on the host computer, all virtual machines with virtual CD readers based on the physical CD reader, such as /dev/cdrom/, can read the inserted CD. Assuming the operating system has automount functionality, the CD should automatically appear in the file system. Virtual CD readers cannot be used to write data to a CD. They are configured as read-only devices.

22.1.3 Adding Virtual CD Readers

Virtual CD readers can be based on a CD inserted into the CD reader or on an ISO image file.

  1. Make sure that the virtual machine is running and the operating system has finished booting.

  2. Insert the desired CD into the physical CD reader or copy the desired ISO image to a location available to Dom0.

  3. Select a new, unused block device in your VM Guest, such as /dev/xvdb.

  4. Choose the CD reader or ISO image that you want to assign to the guest.

  5. When using a real CD reader, use the following command to assign the CD reader to your VM Guest. In this example, the name of the guest is alice:

    xl block-attach alice target=/dev/sr0,vdev=xvdb,access=ro
  6. When assigning an image file, use the following command:

    xl block-attach alice target=/path/to/file.iso,vdev=xvdb,access=ro
  7. A new block device, such as /dev/xvdb, is added to the virtual machine.

  8. If the virtual machine is running Linux, complete the following:

    1. Open a terminal in the virtual machine and enter fdisk -l to verify that the device was properly added. You can also enter ls /sys/block to see all disks available to the virtual machine.

      The CD is recognized by the virtual machine as a virtual disk with a drive designation, for example:

      /dev/xvdb
    2. Enter the command to mount the CD or ISO image using its drive designation. For example,

      mount -o ro /dev/xvdb /mnt

      mounts the CD to a mount point named /mnt.

      The CD or ISO image file should be available to the virtual machine at the specified mount point.

  9. If the virtual machine is running Windows, reboot the virtual machine.

    Verify that the virtual CD reader appears in its My Computer section.

22.1.4 Removing Virtual CD Readers

  1. Make sure that the virtual machine is running and the operating system has finished booting.

  2. If the virtual CD reader is mounted, unmount it from within the virtual machine.

  3. Enter xl block-list alice on the host view of the guest block devices.

  4. Enter xl block-detach alice BLOCK_DEV_ID to remove the virtual device from the guest. If that fails, try to add -f to force the removal.

  5. Press the hardware eject button to eject the CD.

22.2 Remote Access Methods

Some configurations, such as those that include rack-mounted servers, require a computer to run without a video monitor, keyboard, or mouse. This type of configuration is often called headless and requires the use of remote administration technologies.

Typical configuration scenarios and technologies include:

Graphical Desktop with X Window Server

If a graphical desktop, such as GNOME, is installed on the virtual machine host, you can use a remote viewer, such as a VNC viewer. On a remote computer, log in and manage the remote guest environment by using graphical tools, such as tigervnc or virt-viewer.

Text Only

You can use the ssh command from a remote computer to log in to a virtual machine host and access its text-based console. You can then use the xl command to manage virtual machines, and the virt-install command to create new virtual machines.

22.3 VNC Viewer

VNC viewer is used to view the environment of the running guest system in a graphical way. You can use it from Dom0 (known as local access or on-box access), or from a remote computer.

You can use the IP address of a VM Host Server and a VNC viewer to view the display of this VM Guest. When a virtual machine is running, the VNC server on the host assigns the virtual machine a port number to be used for VNC viewer connections. The assigned port number is the lowest port number available when the virtual machine starts. The number is only available for the virtual machine while it is running. After shutting down, the port number might be assigned to other virtual machines.

For example, if ports 1 and 2 and 4 and 5 are assigned to the running virtual machines, the VNC viewer assigns the lowest available port number, 3. If port number 3 is still in use the next time the virtual machine starts, the VNC server assigns a different port number to the virtual machine.

To use the VNC viewer from a remote computer, the firewall must permit access to as many ports as VM Guest systems run from. This means from port 5900 and up. For example, to run 10 VM Guest systems, you need to open the TCP ports 5900:5910.

To access the virtual machine from the local console running a VNC viewer client, enter one of the following commands:

  • vncviewer ::590#

  • vncviewer :#

# is the VNC viewer port number assigned to the virtual machine.

When accessing the VM Guest from a machine other than Dom0, use the following syntax:

vncviewer 192.168.1.20::590#

In this case, the IP address of Dom0 is 192.168.1.20.

22.3.1 Assigning VNC Viewer Port Numbers to Virtual Machines

Although the default behavior of VNC viewer is to assign the first available port number, you should assign a specific VNC viewer port number to a specific virtual machine.

To assign a specific port number on a VM Guest, edit the xl setting of the virtual machine and change the vnclisten to the desired value. Note that for example for port number 5902, specify 2 only, as 5900 is added automatically:

vfb = [ 'vnc=1,vnclisten="localhost:2"' ]

For more information regarding editing the xl settings of a guest domain, see Section 20.1, “XL—Xen Management Tool”.

Tip
Tip

Assign higher port numbers to avoid conflict with port numbers assigned by the VNC viewer, which uses the lowest available port number.

22.3.2 Using SDL instead of a VNC Viewer

If you access a virtual machine's display from the virtual machine host console (known as local or on-box access), you should use SDL instead of VNC viewer. VNC viewer is faster for viewing desktops over a network, but SDL is faster for viewing desktops from the same computer.

To set the default to use SDL instead of VNC, change the virtual machine's configuration information to the following. For instructions, see Section 20.1, “XL—Xen Management Tool”.

vfb = [ 'sdl=1' ]

Remember that, unlike a VNC viewer window, closing an SDL window terminates the virtual machine.

22.4 Virtual Keyboards

When a virtual machine is started, the host creates a virtual keyboard that matches the keymap entry according to the virtual machine's settings. If there is no keymap entry specified, the virtual machine's keyboard defaults to English (US).

To view a virtual machine's current keymap entry, enter the following command on the Dom0:

xl list -l VM_NAME | grep keymap

To configure a virtual keyboard for a guest, use the following snippet:

vfb = [ 'keymap="de"' ]

For a complete list of supported keyboard layouts, see the Keymaps section of the xl.cfg manual page man 5 xl.cfg.

22.5 Dedicating CPU Resources

In Xen it is possible to specify how many and which CPU cores the Dom0 or VM Guest should use to retain its performance. The performance of Dom0 is important for the overall system, as the disk and network drivers are running on it. Also I/O intensive guests' workloads may consume lots of Dom0s' CPU cycles. On the other hand, the performance of VM Guests is also important, to be able to accomplish the task they were set up for.

22.5.1 Dom0

Dedicating CPU resources to Dom0 results in a better overall performance of the virtualized environment because Dom0 has free CPU time to process I/O requests from VM Guests. Failing to dedicate exclusive CPU resources to Dom0 usually results in a poor performance and can cause the VM Guests to function incorrectly.

Dedicating CPU resources involves three basic steps: modifying Xen boot line, binding Dom0's VCPUs to a physical processor, and configuring CPU-related options on VM Guests:

  1. First you need to append the dom0_max_vcpus=X to the Xen boot line. Do so by adding the following line to /etc/default/grub:

    GRUB_CMDLINE_XEN="dom0_max_vcpus=X"

    If /etc/default/grub already contains a line setting GRUB_CMDLINE_XEN, rather append dom0_max_vcpus=X to this line.

    X needs to be replaced by the number of VCPUs dedicated to Dom0.

  2. Update the GRUB 2 configuration file by running the following command:

    grub2-mkconfig -o /boot/grub2/grub.cfg
  3. Reboot for the change to take effect.

  4. The next step is to bind (or pin) each Dom0's VCPU to a physical processor.

    xl vcpu-pin Domain-0 0 0
    xl vcpu-pin Domain-0 1 1

    The first line binds Dom0's VCPU number 0 to the physical processor number 0, while the second line binds Dom0's VCPU number 1 to the physical processor number 1.

  5. Lastly, you need to make sure no VM Guest uses the physical processors dedicated to VCPUs of Dom0. Assuming you are running an 8-CPU system, you need to add

    cpus="2-8"

    to the configuration file of the relevant VM Guest.

22.5.2 VM Guests

It is often necessary to dedicate specific CPU resources to a virtual machine. By default, a virtual machine uses any available CPU core. Its performance can be improved by assigning a reasonable number of physical processors to it as other VM Guests are not allowed to use them after that. Assuming a machine with 8 CPU cores while a virtual machine needs to use 2 of them, change its configuration file as follows:

vcpus=2
cpus="2,3"

The above example dedicates 2 processors to the VM Guest, and these being the 3rd and 4th one, (2 and 3 counted from zero). If you need to assign more physical processors, use the cpus="2-8" syntax.

If you need to change the CPU assignment for a guest named alice in a hotplug manner, do the following on the related Dom0:

xl vcpu-set alice 2
xl vcpu-pin alice 0 2
xl vcpu-pin alice 1 3

The example will dedicate 2 physical processors to the guest, and bind its VCPU 0 to physical processor 2 and VCPU 1 to physical processor 3. Now check the assignment:

xl vcpu-list alice
Name                              ID VCPUs   CPU State   Time(s) CPU Affinity
alice                             4     0     2   -b-       1.9 2-3
alice                             4     1     3   -b-       2.8 2-3

22.6 HVM Features

In Xen some features are only available for fully virtualized domains. They are not very often used, but still may be interesting in some environments.

22.6.1 Specify Boot Device on Boot

Just as with physical hardware, it is sometimes desirable to boot a VM Guest from a different device than its own boot device. For fully virtual machines, it is possible to select a boot device with the boot parameter in a domain xl configuration file:

boot = BOOT_DEVICE

BOOT_DEVICE can be one of c for hard disk, d for CD-ROM, or n for Network/PXE. You can specify multiple options, and they will be attempted in the given order. For example,

boot = dc

boots from CD-ROM, and falls back to the hard disk if CD-ROM is not bootable.

22.6.2 Changing CPUIDs for Guests

To be able to migrate a VM Guest from one VM Host Server to a different VM Host Server, the VM Guest system may only use CPU features that are available on both VM Host Server systems. If the actual CPUs are different on both hosts, it may be necessary to hide some features before the VM Guest is started. This maintains the possibility to migrate the VM Guest between both hosts. For fully virtualized guests, this can be achieved by configuring the cpuid that is available to the guest.

To gain an overview of the current CPU, have a look at /proc/cpuinfo. This contains all the important information that defines the current CPU.

To redefine a CPU, first have a look at the respective cpuid definitions of the CPU vendor. These are available from:

cpuid = "host,tm=0,sse3=0"

The syntax is a comma-separated list of key=value pairs, preceded by the word "host". A few keys take a numerical value, while all others take a single character which describes what to do with the feature bit. See man 5 xl.cfg for a complete list of cpuid keys. The respective bits may be changed by using the following values:

1

Force the corresponding bit to 1

0

Force the corresponding bit to 0

x

Use the values of the default policy

k

Use the values defined by the host

s

Like k, but preserve the value over migrations

Note that counting bits is done from right to left, starting with bit 0.

22.6.3 Increasing the Number of PCI-IRQs

In case you need to increase the default number of PCI-IRQs available to Dom0 and/or VM Guest, you can do so by modifying the Xen kernel command line. Use the command extra_guest_irqs= DOMU_IRGS,DOM0_IRGS. The optional first number DOMU_IRGS is common for all VM Guests, while the optional second number DOM0_IRGS (preceded by a comma) is for Dom0. Changing the setting for VM Guest has no impact on Dom0 and vice versa. For example to change Dom0 without changing VM Guest, use

extra_guest_irqs=,512

23 Administrative Tasks

  • Filename: xen_administrating.xml
  • ID: cha.xen.admin

23.1 The Boot Loader Program

The boot loader controls how the virtualization software boots and runs. You can modify the boot loader properties by using YaST, or by directly editing the boot loader configuration file.

The YaST boot loader program is located at YaST › System › Boot Loader. Click the Bootloader Options tab and select the line containing the Xen kernel as the Default Boot Section.

Boot Loader Settings
Figure 23.1: Boot Loader Settings

Confirm with OK. Next time you boot the host, it will be ready to provide the Xen virtualization environment.

You can use the Boot Loader program to specify functionality, such as:

You can customize your virtualization environment by editing the /etc/default/grub file. Add the following line to this file: GRUB_CMDLINE_XEN="<boot_parameters>". Do not forget to run grub2-mkconfig -o /boot/grub2/grub.cfg after editing the file.

23.2 Sparse Image Files and Disk Space

If the host’s physical disk reaches a state where it has no available space, a virtual machine using a virtual disk based on a sparse image file cannot write to its disk. Consequently, it reports I/O errors.

If this situation occurs, you should free up available space on the physical disk, remount the virtual machine’s file system, and set the file system back to read-write.

To check the actual disk requirements of a sparse image file, use the command du -h <image file>.

To increase the available space of a sparse image file, first increase the file size and then the file system.

Warning
Warning: Back Up Before Resizing

Touching the sizes of partitions or sparse files always bears the risk of data failure. Do not work without a backup.

The resizing of the image file can be done online, while the VM Guest is running. Increase the size of a sparse image file with:

dd if=/dev/zero of=<image file> count=0 bs=1M seek=<new size in MB>

For example, to increase the file /var/lib/xen/images/sles/disk0 to a size of 16GB, use the command:

dd if=/dev/zero of=/var/lib/xen/images/sles/disk0 count=0 bs=1M seek=16000
Note
Note: Increasing Non-Sparse Images

It is also possible to increase the image files of devices that are not sparse files. However, you must know exactly where the previous image ends. Use the seek parameter to point to the end of the image file and use a command similar to the following:

dd if=/dev/zero of=/var/lib/xen/images/sles/disk0 seek=8000 bs=1M count=2000

Be sure to use the right seek, else data loss may happen.

If the VM Guest is running during the resize operation, also resize the loop device that provides the image file to the VM Guest. First detect the correct loop device with the command:

losetup -j /var/lib/xen/images/sles/disk0

Then resize the loop device, for example /dev/loop0, with the following command:

losetup -c /dev/loop0

Finally check the size of the block device inside the guest system with the command fdisk -l /dev/xvdb. The device name depends on the actually increased device.

The resizing of the file system inside the sparse file involves tools that are depending on the actual file system. This is described in detail in the Storage Administration Guide.

23.3 Migrating Xen VM Guest Systems

With Xen it is possible to migrate a VM Guest system from one VM Host Server to another with almost no service interruption. This could be used for example to move a busy VM Guest to a VM Host Server that has stronger hardware or is not yet loaded. Or, if a service of a VM Host Server is required, all VM Guest systems running on this machine can be migrated to other machines to avoid interruption of service. These are only two examples—many more reasons may apply to your personal situation.

Before starting, some preliminary considerations regarding the VM Host Server should be taken into account:

  • All VM Host Server systems should use a similar CPU. The frequency is not so important, but they should be using the same CPU family. To get more information about the used CPU, see cat /proc/cpuinfo.

  • All resources that are used by a specific guest system must be available on all involved VM Host Server systems—for example all used block devices must exist on both VM Host Server systems.

  • If the hosts included in the migration process run in different subnets, make sure that either DHCP relay is available to the guests, or for guests with static network configuration, set up the network manually.

  • Using special features like PCI Pass-Through may be problematic. Do not implement these when deploying for an environment that should migrate VM Guest systems between different VM Host Server systems.

  • For fast migrations, a fast network is mandatory. If possible, use GB Ethernet and fast switches. Deploying VLAN might also help avoid collisions.

23.3.1 Preparing Block Devices for Migrations

The block devices needed by the VM Guest system must be available on all involved VM Host Server systems. This is done by implementing some kind of shared storage that serves as container for the root file system of the migrated VM Guest system. Common possibilities include:

  • iSCSI can be set up to give access to the same block devices from different systems at the same time. For more information about iSCSI, see Chapter 14, Mass Storage over IP Networks: iSCSI.

  • NFS is a widely used root file system that can easily be accessed from different locations. For more information, see Chapter 27, Sharing File Systems with NFS.

  • DRBD can be used if only two VM Host Server systems are involved. This gives some extra data security, because the used data is mirrored over the network. For more information, see the SUSE Linux Enterprise High Availability Extension 12 SP3 documentation at http://www.suse.com/doc/.

  • SCSI can also be used if the available hardware permits shared access to the same disks.

  • NPIV is a special mode to use Fibre channel disks. However, in this case all migration hosts must be attached to the same Fibre channel switch. For more information about NPIV, see Section 21.1, “Mapping Physical Storage to Virtual Disks”. Commonly, this works if the Fibre channel environment supports 4 Gbit or faster connections.

23.3.2 Migrating VM Guest Systems

The actual migration of the VM Guest system is done with the command:

xl migrate <domain_name> <host>

The speed of the migration depends on how fast the memory print can be saved to disk, sent to the new VM Host Server and loaded there. This means that small VM Guest systems can be migrated faster than big systems with a lot of memory.

23.4 Monitoring Xen

For a regular operation of many virtual guests, having a possibility to check the sanity of all the different VM Guest systems is indispensable. Xen offers several tools besides the system tools to gather information about the system.

Tip
Tip: Monitoring the VM Host Server

Basic monitoring of the VM Host Server (I/O and CPU) is available via the Virtual Machine Manager. Refer to Section 10.8.1, “Monitoring with Virtual Machine Manager” for details.

23.4.1 Monitor Xen with xentop

The preferred terminal application to gather information about Xen virtual environment is xentop. Unfortunately, this tool needs a rather broad terminal, else it inserts line breaks into the display.

xentop has several command keys that can give you more information about the system that is monitored. Some of the more important are:

D

Change the delay between the refreshes of the screen.

N

Also display network statistics. Note, that only standard configurations will be displayed. If you use a special configuration like a routed network, no network will be displayed.

B

Display the respective block devices and their cumulated usage count.

For more information about xentop see the manual page man 1 xentop.

Tip
Tip: virt-top

libvirt offers the hypervisor-agnostic tool virt-top, which is recommended for monitoring VM Guests. See Section 10.8.2, “Monitoring with virt-top for details.

23.4.2 Additional Tools

There are many system tools that also help monitoring or debugging a running SUSE Linux Enterprise system. Many of these are covered in Chapter 2, System Monitoring Utilities. Especially useful for monitoring a virtualization environment are the following tools:

ip

The command line utility ip may be used to monitor arbitrary network interfaces. This is especially useful if you have set up a network that is routed or applied a masqueraded network. To monitor a network interface with the name alice.0, run the following command:

watch ip -s link show alice.0
brctl

In a standard setup, all the Xen VM Guest systems are attached to a virtual network bridge. brctl allows you to determine the connection between the bridge and the virtual network adapter in the VM Guest system. For example, the output of brctl show may look like the following:

bridge name     bridge id               STP enabled     interfaces
br0             8000.000476f060cc       no              eth0
                                                        vif1.0
br1             8000.00001cb5a9e7       no              vlan22

This shows that there are two virtual bridges defined on the system. One is connected to the physical Ethernet device eth0, the other one is connected to a VLAN interface vlan22.

There is only one guest interface active in this setup, vif1.0. This means that the guest with ID 1 has an Ethernet interface eth0 assigned, that is connected to br0 in the VM Host Server.

iptables-save

Especially when using masquerade networks, or if several Ethernet interfaces are set up together with a firewall setup, it may be helpful to check the current firewall rules.

The command iptables may be used to check all the different firewall settings. To list all the rules of a chain, or even of the complete setup, you may use the commands iptables-save or iptables -S.

23.5 Providing Host Information for VM Guest Systems

In a standard Xen environment, the VM Guest systems have only very limited information about the VM Host Server system they are running on. If a guest should know more about the VM Host Server it runs on, vhostmd can provide more information to selected guests. To set up your system to run vhostmd, proceed as follows:

  1. Install the package vhostmd on the VM Host Server.

  2. To add or remove metric sections from the configuration, edit the file /etc/vhostmd/vhostmd.conf. However, the default works well.

  3. Check the validity of the vhostmd.conf configuration file with the command:

    cd /etc/vhostmd
    xmllint --postvalid --noout vhostmd.conf
  4. Start the vhostmd daemon with the command sudo systemctl start vhostmd.

    If vhostmd should be started automatically during start-up of the system, run the command:

    sudo systemctl enable vhostmd
  5. Attach the image file /dev/shm/vhostmd0 to the VM Guest system named alice with the command:

    xl block-attach opensuse /dev/shm/vhostmd0,,xvdb,ro
  6. Log on the VM Guest system.

  7. Install the client package vm-dump-metrics.

  8. Run the command vm-dump-metrics. To save the result to a file, use the option -d <filename>.

The result of the vm-dump-metrics is an XML output. The respective metric entries follow the DTD /etc/vhostmd/metric.dtd.

For more information, see the manual pages man 8 vhostmd and /usr/share/doc/vhostmd/README on the VM Host Server system. On the guest, see the manual page man 1 vm-dump-metrics.

24 XenStore: Configuration Database Shared between Domains

  • Filename: xen_xenstore.xml
  • ID: cha.xen.xenstore

This section introduces basic information about XenStore, its role in the Xen environment, the directory structure of files used by XenStore, and the description of XenStore's commands.

24.1 Introduction

XenStore is a database of configuration and status information shared between VM Guests and the management tools running in Dom0. VM Guests and the management tools read and write to XenStore to convey configuration information, status updates, and state changes. The XenStore database is managed by Dom0 and supports simple operations such as reading and writing a key. VM Guests and management tools can be notified of any changes in XenStore by watching entries of interest. Note that the xenstored daemon is managed by the xencommons service.

XenStore is located on Dom0 in a single database file /var/lib/xenstored/tdb (tdb represents tree database).

24.2 File System Interface

XenStore database content is represented by a virtual file system similar to /proc (for more information on /proc, see Section 2.6, “The /proc File System”). The tree has three main paths: /vm, /local/domain, and /tool.

  • /vm - stores information about the VM Guest configuration.

  • /local/domain - stores information about VM Guest on the local node.

  • /tool - stores general information about various tools.

Tip
Tip

Each VM Guest has two different ID numbers. The universal unique identifier (UUID) remains the same even if the VM Guest is migrated to another machine. The domain identifier (DOMID) is an identification number that represents a particular running instance. It typically changes when the VM Guest is migrated to another machine.

24.2.1 XenStore Commands

The file system structure of the XenStore database can be operated with the following commands:

xenstore-ls

Displays the full dump of the XenStore database.

xenstore-readpath_to_xenstore_entry

Displays the value of the specified XenStore entry.

xenstore-existsxenstore_path

Reports whether the specified XenStore path exists.

xenstore-listxenstore_path

Displays all the children entries of the specified XenStore path.

xenstore-writepath_to_xenstore_entry

Updates the value of the specified XenStore entry.

xenstore-rmxenstore_path

Removes the specified XenStore entry or directory.

xenstore-chmodxenstore_pathmode

Updates the read/write permission on the specified XenStore path.

xenstore-control

Sends a command to the xenstored back-end, such as triggering an integrity check.

24.2.2 /vm

The /vm path is indexed by the UUID of each VM Guest, and stores configuration information such as the number of virtual CPUs and the amount of allocated memory. There is a /vm/<uuid> directory for each VM Guest. To list the directory content, use xenstore-list.

# xenstore-list /vm
00000000-0000-0000-0000-000000000000
9b30841b-43bc-2af9-2ed3-5a649f466d79-1

The first line of the output belongs to Dom0, and the second one to a running VM Guest. The following command lists all the entries related to the VM Guest:

# xenstore-list /vm/9b30841b-43bc-2af9-2ed3-5a649f466d79-1
image
rtc
device
pool_name
shadow_memory
uuid
on_reboot
start_time
on_poweroff
bootloader_args
on_crash
vcpus
vcpu_avail
bootloader
name

To read a value of an entry, for example the number of virtual CPUs dedicated to the VM Guest, use xenstore-read:

# xenstore-read /vm/9b30841b-43bc-2af9-2ed3-5a649f466d79-1/vcpus
1

A list of selected /vm/<uuid> entries follows:

uuid

UUID of the VM Guest. It does not change during the migration process.

on_reboot

Specifies whether to destroy or restart the VM Guest in response to a reboot request.

on_poweroff

Specifies whether to destroy or restart the VM Guest in response to a halt request.

on_crash

Specifies whether to destroy or restart the VM Guest in response to a crash.

vcpus

Number of virtual CPUs allocated to the VM Guest.

vcpu_avail

Bitmask of active virtual CPUs for the VM Guest. The bitmask has several bits equal to the value of vcpus, with a bit set for each online virtual CPU.

name

The name of the VM Guest.

Regular VM Guests (not Dom0) use the /vm/<uuid>/image path:

# xenstore-list /vm/9b30841b-43bc-2af9-2ed3-5a649f466d79-1/image
ostype
kernel
cmdline
ramdisk
dmargs
device-model
display

An explanation of the used entries follows:

ostype

The OS type of the VM Guest.

kernel

The path on Dom0 to the kernel for the VM Guest.

cmdline

The kernel command line for the VM Guest used when booting.

ramdisk

The path on Dom0 to the RAM disk for the VM Guest.

dmargs

Shows arguments passed to the QEMU process. If you look at the QEMU process with ps, you should see the same arguments as in /vm/<uuid>/image/dmargs.

24.2.3 /local/domain/<domid>

This path is indexed by the running domain (VM Guest) ID, and contains information about the running VM Guest. Remember that the domain ID changes during VM Guest migration. The following entries are available:

vm

The path of the /vm directory for this VM Guest.

on_reboot, on_poweroff, on_crash, name

See identical options in Section 24.2.2, “/vm

domid

Domain identifier for the VM Guest.

cpu

The current CPU to which the VM Guest is pinned.

cpu_weight

The weight assigned to the VM Guest for scheduling purposes. Higher weights use the physical CPUs more often.

Apart from the individual entries described above, there are also several subdirectories under /local/domain/<domid>, containing specific entries. To see all entries available, refer to XenStore Reference.

/local/domain/<domid>/memory

Contains memory information. /local/domain/<domid>/memory/target contains target memory size for the VM Guest (in kilobytes).

/local/domain/<domid>/console

Contains information about a console used by the VM Guest.

/local/domain/<domid>/backend

Contains information about all back-end devices used by the VM Guest. The path has subdirectories of its own.

/local/domain/<domid>/device

Contains information about the front-end devices for the VM Guest.

/local/domain/<domid>/device-misc

Contains miscellaneous information about devices.

/local/domain/<domid>/store

Contains information about the VM Guest's store.

25 Xen as a High-Availability Virtualization Host

  • Filename: xen_ha_setup.xml
  • ID: cha.xen.ha

Setting up two Xen hosts as a failover system has several advantages compared to a setup where every server runs on dedicated hardware.

  • Failure of a single server does not cause major interruption of the service.

  • A single big machine is normally way cheaper than multiple smaller machines.

  • Adding new servers as needed is a trivial task.

  • The usage of the server is improved, which has positive effects on the power consumption of the system.

The setup of migration for Xen hosts is described in Section 23.3, “Migrating Xen VM Guest Systems”. In the following, several typical scenarios are described.

25.1 Xen HA with Remote Storage

Xen can directly provide several remote block devices to the respective Xen guest systems. These include iSCSI, NPIV, and NBD. All of these may be used to do live migrations. When a storage system is already in place, first try to use the same device type you already used in the network.

If the storage system cannot be used directly but provides a possibility to offer the needed space over NFS, it is also possible to create image files on NFS. If the NFS file system is available on all Xen host systems, this method also allows live migrations of Xen guests.

When setting up a new system, one of the main considerations is whether a dedicated storage area network should be implemented. The following possibilities are available:

Table 25.1: Xen Remote Storage

Method

Complexity

Comments

Ethernet

low

Note that all block device traffic goes over the same Ethernet interface as the network traffic. This may be limiting the performance of the guest.

Ethernet dedicated to storage.

medium

Running the storage traffic over a dedicated Ethernet interface may eliminate a bottleneck on the server side. However, planning your own network with your own IP address range and possibly a VLAN dedicated to storage requires numerous considerations.

NPIV

high

NPIV is a method to virtualize Fibre channel connections. This is available with adapters that support a data rate of at least 4 Gbit/s and allows the setup of complex storage systems.

Typically, a 1 Gbit/s Ethernet device can fully use a typical hard disk or storage system. When using very fast storage systems, such an Ethernet device will probably limit the speed of the system.

25.2 Xen HA with Local Storage

For space or budget reasons, it may be necessary to rely on storage that is local to the Xen host systems. To still maintain the possibility of live migrations, it is necessary to build block devices that are mirrored to both Xen hosts. The software that allows this is called Distributed Replicated Block Device (DRBD).

If a system that uses DRBD to mirror the block devices or files between two Xen hosts should be set up, both hosts should use the identical hardware. If one of the hosts has slower hard disks, both hosts will suffer from this limitation.

During the setup, each of the required block devices should use its own DRBD device. The setup of such a system is quite a complex task.

25.3 Xen HA and Private Bridges

When using several guest systems that need to communicate between each other, it is possible to do this over the regular interface. However, for security reasons it may be advisable to create a bridge that is only connected to guest systems.

In an HA environment that also should support live migrations, such a private bridge must be connected to the other Xen hosts. This is possible by using dedicated physical Ethernet devices and a dedicated network.

A different implementation method is using VLAN interfaces. In that case, all the traffic goes over the regular Ethernet interface. However, the VLAN interface does not get the regular traffic, because only the VLAN packets that are tagged for the correct VLAN are forwarded.

For more information about the setup of a VLAN interface see Section 13.2.3, “Using VLAN Interfaces”.

Part V Managing Virtual Machines with QEMU

26 QEMU Overview

QEMU is a fast, cross-platform open source machine emulator which can emulate a huge number of hardware architectures for you. QEMU lets you run a complete unmodified operating system (VM Guest) on top of your existing system (VM Host Server).

27 Setting Up a KVM VM Host Server

This section documents how to set up and use SUSE Linux Enterprise Server 12 SP3 as a QEMU-KVM based virtual machine host.

28 Guest Installation

The libvirt-based tools such as virt-manager and virt-install offer convenient interfaces to set up and manage virtual machines. They act as a kind of wrapper for the qemu-system-ARCHcommand. However, it is also possible to use qemu-system-ARCH directly without using libvirt-based tools.

29 Running Virtual Machines with qemu-system-ARCH

Once you have a virtual disk image ready (for more information on disk images, see Section 28.2, “Managing Disk Images with qemu-img”), it is time to start the related virtual machine. Section 28.1, “Basic Installation with qemu-system-ARCH” introduced simple commands to install and run a VM Guest. …

30 Virtual Machine Administration Using QEMU Monitor

When QEMU is running, a monitor console is provided for performing interaction with the user. Using the commands available in the monitor console, it is possible to inspect the running operating system, change removable media, take screenshots or audio grabs and control other aspects of the virtual …

26 QEMU Overview

  • Filename: qemu_overview.xml
  • ID: cha.qemu.overview

QEMU is a fast, cross-platform open source machine emulator which can emulate a huge number of hardware architectures for you. QEMU lets you run a complete unmodified operating system (VM Guest) on top of your existing system (VM Host Server).

You can also use QEMU for debugging purposes—you can easily stop your running virtual machine, inspect its state and save and restore it later.

QEMU consists of the following parts:

  • processor emulator (x86, z Systems, PowerPC, Sparc)

  • emulated devices (graphic card, network card, hard disks, mice)

  • generic devices used to connect the emulated devices to the related host devices

  • descriptions of the emulated machines (PC, Power Mac)

  • debugger

  • user interface used to interact with the emulator

QEMU is central to KVM and Xen Virtualization, where it provides the general machine emulation. Xen's usage of QEMU is somewhat hidden from the user, while KVM's usage exposes most QEMU features transparently. If the VM Guest hardware architecture is the same as the VM Host Server's architecture, QEMU can take advantage of the KVM acceleration (SUSE only supports QEMU with the KVM acceleration loaded).

Apart from providing a core virtualization infrastructure and processor-specific drivers, QEMU also provides an architecture-specific user space program for managing VM Guests. Depending on the architecture this program is one of:

  • qemu-system-i386

  • qemu-system-s390x

  • qemu-system-x86_64

In the following this command is called qemu-system-ARCH; in examples the qemu-system-x86_64 command is used.

27 Setting Up a KVM VM Host Server

  • Filename: qemu_host_installation.xml
  • ID: cha.qemu.host

This section documents how to set up and use SUSE Linux Enterprise Server 12 SP3 as a QEMU-KVM based virtual machine host.

Tip
Tip: Resources

In general, the virtual guest system needs the same hardware resources as when installed on a physical machine. The more guests you plan to run on the host system, the more hardware resources—CPU, disk, memory, and network—you need to add to the VM Host Server.

27.1 CPU Support for Virtualization

To run KVM, your CPU must support virtualization, and virtualization needs to be enabled in BIOS. The file /proc/cpuinfo includes information about your CPU features.

To find out whether your system supports virtualization, see Section 7.3, “KVM Hardware Requirements”.

27.2 Required Software

The KVM host requires several packages to be installed. To install all necessary packages, do the following:

  1. Run YaST ›  Virtualization › Install Hypervisor and Tools.

    Installing the KVM Hypervisor and Tools
    Figure 27.1: Installing the KVM Hypervisor and Tools
  2. Select KVM server and preferably also KVM tools, and confirm with Accept.

  3. During the installation process, you can optionally let YaST create a Network Bridge for you automatically. If you do not plan to dedicate an additional physical network card to your virtual guests, network bridge is a standard way to connect the guest machines to the network.

    Network Bridge
    Figure 27.2: Network Bridge
  4. After all the required packages are installed (and new network setup activated), try to load the KVM kernel module relevant for your CPU type—kvm-intel or kvm-amd:

    root # modprobe kvm-intel

    Check if the module is loaded into memory:

    tux > lsmod | grep kvm
    kvm_intel              64835  6
    kvm                   411041  1 kvm_intel

    Now the KVM host is ready to serve KVM VM Guests. For more information, see Chapter 29, Running Virtual Machines with qemu-system-ARCH.

27.3 KVM Host-Specific Features

You can improve the performance of KVM-based VM Guests by letting them fully use specific features of the VM Host Server's hardware (paravirtualization). This section introduces techniques to make the guests access the physical host's hardware directly—without the emulation layer—to make the most use of it.

Tip
Tip

Examples included in this section assume basic knowledge of the qemu-system-ARCH command line options. For more information, see Chapter 29, Running Virtual Machines with qemu-system-ARCH.

27.3.1 Using the Host Storage with virtio-scsi

virtio-scsi is an advanced storage stack for KVM. It replaces the former virtio-blk stack for SCSI devices pass-through. It has several advantages over virtio-blk:

Improved scalability

KVM guests have a limited number of PCI controllers, which results in a limited number of possibly attached devices. virtio-scsi solves this limitation by grouping multiple storage devices on a single controller. Each device on a virtio-scsi controller is represented as a logical unit, or LUN.

Standard command set

virtio-blk uses a small set of commands that need to be known to both the virtio-blk driver and the virtual machine monitor, and so introducing a new command requires updating both the driver and the monitor.

By comparison, virtio-scsi does not define commands, but rather a transport protocol for these commands following the industry-standard SCSI specification. This approach is shared with other technologies, such as Fibre Channel, ATAPI, and USB devices.

Device naming

virtio-blk devices are presented inside the guest as /dev/vdX, which is different from device names in physical systems and may cause migration problems.

virtio-scsi keeps the device names identical to those on physical systems, making the virtual machines easily relocatable.

SCSI device pass-through

For virtual disks backed by a whole LUN on the host, it is preferable for the guest to send SCSI commands directly to the LUN (pass-through). This is limited in virtio-blk, as guests need to use the virtio-blk protocol instead of SCSI command pass-through, and, moreover, it is not available for Windows guests. virtio-scsi natively removes these limitations.

27.3.1.1 virtio-scsi Usage

KVM supports the SCSI pass-through feature with the virtio-scsi-pci device:

qemu-system-x86_64 [...] \
-device virtio-scsi-pci,id=scsi

27.3.2 Accelerated Networking with vhost-net

The vhost-net module is used to accelerate KVM's paravirtualized network drivers. It provides better latency and greater network throughput. Use the vhost-net driver by starting the guest with the following example command line:

qemu-system-x86_64 [...] \
-netdev tap,id=guest0,vhost=on,script=no \
-net nic,model=virtio,netdev=guest0,macaddr=00:16:35:AF:94:4B

Note that guest0 is an identification string of the vhost-driven device.

27.3.3 Scaling Network Performance with Multiqueue virtio-net

As the number of virtual CPUs increases in VM Guests, QEMU offers a way of improving the network performance using multiqueue. Multiqueue virtio-net scales the network performance by allowing VM Guest virtual CPUs to transfer packets in parallel. Multiqueue support is required on both the VM Host Server and VM Guest sides.

Tip
Tip: Performance Benefit

The multiqueue virtio-net solution is most beneficial in the following cases:

  • Network traffic packets are large.

  • VM Guest has many connections active at the same time, mainly between the guest systems, or between the guest and the host, or between the guest and an external system.

  • The number of active queues is equal to the number of virtual CPUs in the VM Guest.

Note
Note

While multiqueue virtio-net increases the total network throughput, it increases CPU consumption as it uses of the virtual CPU's power.

Procedure 27.1: How to Enable Multiqueue virtio-net

The following procedure lists important steps to enable the multiqueue feature with qemu-system-ARCH. It assumes that a tap network device with multiqueue capability (supported since kernel version 3.8) is set up on the VM Host Server.

  1. In qemu-system-ARCH, enable multiqueue for the tap device:

    -netdev tap,vhost=on,queues=2*N

    where N stands for the number of queue pairs.

  2. In qemu-system-ARCH, enable multiqueue and specify MSI-X (Message Signaled Interrupt) vectors for the virtio-net-pci device:

    -device virtio-net-pci,mq=on,vectors=2*N+2

    where the formula for the number of MSI-X vectors results from: N vectors for TX (transmit) queues, N for RX (receive) queues, one for configuration purposes, and one for possible VQ (vector quantization) control.

  3. In VM Guest, enable multiqueue on the relevant network interface (eth0 in this example):

    ethtool -L eth0 combined 2*N

The resulting qemu-system-ARCH command line will look similar to the following example:

qemu-system-x86_64 [...] -netdev tap,id=guest0,queues=8,vhost=on \
-device virtio-net-pci,netdev=guest0,mq=on,vectors=10

Note that the id of the network device (guest0 ) needs to be identical for both options.

Inside the running VM Guest, specify the following command as root:

ethtool -L eth0 combined 8

Now the guest system networking uses the multiqueue support from the qemu-system-ARCH hypervisor.

27.3.4 VFIO: Secure Direct Access to Devices

Directly assigning a PCI device to a VM Guest (PCI pass-through) avoids performance issues caused by avoiding any emulation in performance-critical paths. VFIO replaces the traditional KVM PCI Pass-Through device assignment. A prerequisite for this feature is a VM Host Server configuration as described in Important: Requirements for VFIO and SR-IOV.

To be able to assign a PCI device via VFIO to a VM Guest, you need to find out which IOMMU Group it belongs to. The IOMMU (input/output memory management unit that connects a direct memory access-capable I/O bus to the main memory) API supports the notion of groups. A group is a set of devices that can be isolated from all other devices in the system. Groups are therefore the unit of ownership used by VFIO.

Procedure 27.2: Assigning a PCI Device to a VM Guest via VFIO
  1. Identify the host PCI device to assign to the guest.

    tux > sudo lspci -nn
    [...]
    00:10.0 Ethernet controller [0200]: Intel Corporation 82576 \
    Virtual Function [8086:10ca] (rev 01)
    [...]

    Note down the device ID (00:10.0 in this case) and the vendor ID (8086:10ca).

  2. Find the IOMMU group of this device:

    tux > sudo readlink /sys/bus/pci/devices/0000\:00\:10.0/iommu_group
    ../../../kernel/iommu_groups/20

    The IOMMU group for this device is 20. Now you can check the devices belonging to the same IOMMU group:

    ls -l /sys/bus/pci/devices/0000:01:10.0/iommu_group/devices/0000:01:10.0
    [...] 0000:00:1e.0 -> ../../../../devices/pci0000:00/0000:00:1e.0
    [...] 0000:01:10.0 -> ../../../../devices/pci0000:00/0000:00:1e.0/0000:01:10.0
    [...] 0000:01:10.1 -> ../../../../devices/pci0000:00/0000:00:1e.0/0000:01:10.1
  3. Unbind the device from the device driver:

    sudo echo "0000:01:10.0" > /sys/bus/pci/devices/0000\:01\:10.0/driver/unbind
  4. Bind the device to the vfio-pci driver using the vendor ID from step 1:

    sudo echo "8086 153a" > /sys/bus/pci/drivers/vfio-pci/new_id

    A new device /dev/vfio/IOMMU_GROUP will be created as a result, /dev/vfio/20 in this case.

  5. Change the ownership of the newly created device:

    chown qemu.qemu /dev/vfio/DEVICE
  6. Now run the VM Guest with the PCI device assigned.

    qemu-system-ARCH [...] -device
         vfio-pci,host=00:10.0,id=ID
Important
Important: No Hotplugging

As of SUSE Linux Enterprise Server 12 SP3 hotplugging of PCI devices passed to a VM Guest via VFIO is not supported.

You can find more detailed information on the VFIO driver in the /usr/src/linux/Documentation/vfio.txt file (package kernel-source needs to be installed).

27.3.5 VirtFS: Sharing Directories between Host and Guests

VM Guests usually run in a separate computing space—they are provided their own memory range, dedicated CPUs, and file system space. The ability to share parts of the VM Host Server's file system makes the virtualization environment more flexible by simplifying mutual data exchange. Network file systems, such as CIFS and NFS, have been the traditional way of sharing directories. But as they are not specifically designed for virtualization purposes, they suffer from major performance and feature issues.

KVM introduces a new optimized method called VirtFS (sometimes called file system pass-through). VirtFS uses a paravirtual file system driver, which avoids converting the guest application file system operations into block device operations, and then again into host file system operations.

You typically use VirtFS for the following situations:

  • To access a shared directory from several guests, or to provide guest-to-guest file system access.

  • To replace the virtual disk as the root file system to which the guest's RAM disk connects during the guest boot process.

  • To provide storage services to different customers from a single host file system in a cloud environment.

27.3.5.1 Implementation

In QEMU, the implementation of VirtFS is simplified by defining two types of devices:

  • virtio-9p-pci device which transports protocol messages and data between the host and the guest.

  • fsdev device which defines the export file system properties, such as file system type and security model.

Example 27.1: Exporting Host's File System with VirtFS
qemu-system-x86_64 [...] \
-fsdev local,id=exp11,path=/tmp/2,security_model=mapped3 \
-device virtio-9p-pci,fsdev=exp14,mount_tag=v_tmp5

1

Identification of the file system to be exported.

2

File system path on the host to be exported.

3

Security model to be used—mapped keeps the guest file system modes and permissions isolated from the host, while none invokes a pass-through security model in which permission changes on the guest's files are reflected on the host as well.

4

The exported file system ID defined before with -fsdev id= .

5

Mount tag used later on the guest to mount the exported file system.

Such an exported file system can be mounted on the guest as follows:

sudo mount -t 9p -o trans=virtio v_tmp /mnt

where v_tmp is the mount tag defined earlier with -device mount_tag= and /mnt is the mount point where you want to mount the exported file system.

27.3.6 KSM: Sharing Memory Pages between Guests

Kernel Same Page Merging (KSM) is a Linux kernel feature that merges identical memory pages from multiple running processes into one memory region. Because KVM guests run as processes under Linux, KSM provides the memory overcommit feature to hypervisors for more efficient use of memory. Therefore, if you need to run multiple virtual machines on a host with limited memory, KSM may be helpful to you.

KSM stores its status information in the files under the /sys/kernel/mm/ksm directory:

tux > ls -1 /sys/kernel/mm/ksm
full_scans
merge_across_nodes
pages_shared
pages_sharing
pages_to_scan
pages_unshared
pages_volatile
run
sleep_millisecs

For more information on the meaning of the /sys/kernel/mm/ksm/* files, see /usr/src/linux/Documentation/vm/ksm.txt (package kernel-source).

To use KSM, do the following.

  1. Although SLES includes KSM support in the kernel, it is disabled by default. To enable it, run the following command:

    root # echo 1 > /sys/kernel/mm/ksm/run
  2. Now run several VM Guests under KVM and inspect the content of files pages_sharing and pages_shared, for example:

    while [ 1 ]; do cat /sys/kernel/mm/ksm/pages_shared; sleep 1; done
    13522
    13523
    13519
    13518
    13520
    13520
    13528

28 Guest Installation

  • Filename: qemu_guest_installation.xml
  • ID: cha.qemu.guest_inst

The libvirt-based tools such as virt-manager and virt-install offer convenient interfaces to set up and manage virtual machines. They act as a kind of wrapper for the qemu-system-ARCHcommand. However, it is also possible to use qemu-system-ARCH directly without using libvirt-based tools.

Warning
Warning: qemu-system-ARCH and libvirt

Virtual Machines created with qemu-system-ARCH are not "visible" for the libvirt-based tools.

28.1 Basic Installation with qemu-system-ARCH

In the following example, a virtual machine for a SUSE Linux Enterprise Server 11 installation is created. For detailed information on the commands, refer to the respective man pages.

If you do not already have an image of a system that you want to run in a virtualized environment, you need to create one from the installation media. In such case, you need to prepare a hard disk image, and obtain an image of the installation media or the media itself.

Create a hard disk with qemu-img.

qemu-img create1 -f raw2 /images/sles/hda3 8G4

1

The subcommand create tells qemu-img to create a new image.

2

Specify the disk's format with the -f parameter.

3

The full path to the image file.

4

The size of the image—8 GB in this case. The image is created as a Sparse image file file that grows when the disk is filled with data. The specified size defines the maximum size to which the image file can grow.

After at least one hard disk image is created, you can set up a virtual machine with qemu-system-ARCH that will boot into the installation system:

root # qemu-system-x86_64 -name "sles"1-machine accel=kvm -M pc2 -m 7683 \
-smp 24 -boot d5 \
-drive file=/images/sles/hda,if=virtio,index=0,media=disk,format=raw6 \
-drive file=/isos/SLES-11-SP3-DVD-x86_64-GM-DVD1.iso,index=1,media=cdrom7 \
-net nic,model=virtio,macaddr=52:54:00:05:11:118 -net user \
-vga cirrus9 -balloon virtio10

1

Name of the virtual machine that will be displayed in the window caption and be used for the VNC server. This name must be unique.

2

Specifies the machine type. Use qemu-system-ARCH -M ? to display a list of valid parameters. pc is the default Standard PC.

3

Maximum amount of memory for the virtual machine.

4

Defines an SMP system with two processors.

5

Specifies the boot order. Valid values are a, b (floppy 1 and 2), c (first hard disk), d (first CD-ROM), or n to p (Ether-boot from network adapter 1-3). Defaults to c.

6

Defines the first (index=0) hard disk. It will be accessed as a paravirtualized (if=virtio) drive in raw format.

7

The second (index=1) image drive will act as a CD-ROM.

8

Defines a paravirtualized (model=virtio) network adapter with the MAC address 52:54:00:05:11:11. Be sure to specify a unique MAC address, otherwise a network conflict may occur.

9

Specifies the graphic card. If you specify none, the graphic card will be disabled.

10

Defines the paravirtualized balloon device that allows to dynamically change the amount of memory (up to the maximum value specified with the parameter -m).

After the installation of the guest operating system finishes, you can start the related virtual machine without the need to specify the CD-ROM device:

root # qemu-system-x86_64 -name "sles" -machine type=pc,accel=kvm -m 768 \
-smp 2 -boot c \
-drive file=/images/sles/hda,if=virtio,index=0,media=disk,format=raw \
-net nic,model=virtio,macaddr=52:54:00:05:11:11 \
-vga cirrus -balloon virtio

28.2 Managing Disk Images with qemu-img

In the previous section (see Section 28.1, “Basic Installation with qemu-system-ARCH), we used the qemu-img command to create an image of a hard disk. You can, however, use qemu-img for general disk image manipulation. This section introduces qemu-img subcommands to help manage the disk images flexibly.

28.2.1 General Information on qemu-img Invocation

qemu-img uses subcommands (like zypper does) to do specific tasks. Each subcommand understands a different set of options. Some options are general and used by more of these subcommands, while some are unique to the related subcommand. See the qemu-img manual page (man 1 qemu-img) for a list of all supported options. qemu-img uses the following general syntax:

tux > qemu-img subcommand [options]

and supports the following subcommands:

create

Creates a new disk image on the file system.

check

Checks an existing disk image for errors.

compare

Check if two images have the same content.

map

Dumps the metadata of the image file name and its backing file chain.

amend

Amends the image format specific options for the image file name.

convert

Converts an existing disk image to a new one in a different format.

info

Displays information about the relevant disk image.

snapshot

Manages snapshots of existing disk images.

commit

Applies changes made to an existing disk image.

rebase

Creates a new base image based on an existing image.

resize

Increases or decreases the size of an existing image.

28.2.2 Creating, Converting and Checking Disk Images

This section describes how to create disk images, check their condition, convert a disk image from one format to another, and get detailed information about a particular disk image.

28.2.2.1 qemu-img create

Use qemu-img create to create a new disk image for your VM Guest operating system. The command uses the following syntax:

tux > qemu-img create -f fmt1 -o options2 fname3 size4

1

The format of the target image. Supported formats are qed, qcow2, and raw.

2

Some image formats support additional options to be passed on the command line. You can specify them here with the -o option. The raw image format supports only the size option, so it is possible to insert -o size=8G instead of adding the size option at the end of the command.

3

Path to the target disk image to be created.

4

Size of the target disk image (if not already specified with the -o size=<image_size> option. Optional suffixes for the image size are K (kilobyte), M (megabyte), G (gigabyte), or T (terabyte).

To create a new disk image sles.raw in the directory /images growing up to a maximum size of 4 GB, run the following command:

tux > qemu-img create -f raw -o size=4G /images/sles.raw
Formatting '/images/sles.raw', fmt=raw size=4294967296

tux > ls -l /images/sles.raw
-rw-r--r-- 1 tux users 4294967296 Nov 15 15:56 /images/sles.raw

tux > qemu-img info /images/sles.raw
image: /images/sles11.raw
file format: raw
virtual size: 4.0G (4294967296 bytes)
disk size: 0

As you can see, the virtual size of the newly created image is 4 GB, but the actual reported disk size is 0 as no data has been written to the image yet.

Tip
Tip: VM Guest Images on the Btrfs File System

If you need to create a disk image on the Btrfs file system, you can use nocow=on to reduce the performance overhead created by the copy-on-write feature of Btrfs:

tux > qemu-img create -o nocow=on test.img 8G

If you, however, want to use copy-on-write (for example for creating snapshots or sharing them across virtual machines), then leave the command line without the nocow option.

28.2.2.2 qemu-img convert

Use qemu-img convert to convert disk images to another format. To get a complete list of image formats supported by QEMU, run qemu-img -h and look at the last line of the output. The command uses the following syntax:

tux > qemu-img convert -c1 -f fmt2 -O out_fmt3 -o options4 fname5 out_fname6

1

Applies compression on the target disk image. Only qcow and qcow2 formats support compression.

2

The format of the source disk image. It is usually autodetected and can therefore be omitted.

3

The format of the target disk image.

4

Specify additional options relevant for the target image format. Use -o ? to view the list of options supported by the target image format.

5

Path to the source disk image to be converted.

6

Path to the converted target disk image.

tux > qemu-img convert -O vmdk /images/sles.raw \
/images/sles.vmdk

tux > ls -l /images/
-rw-r--r-- 1 tux users 4294967296 16. lis 10.50 sles.raw
-rw-r--r-- 1 tux users 2574450688 16. lis 14.18 sles.vmdk

To see a list of options relevant for the selected target image format, run the following command (replace vmdk with your image format):

tux > qemu-img convert -O vmdk /images/sles.raw \
/images/sles.vmdk -o ?
Supported options:
size             Virtual disk size
backing_file     File name of a base image
compat6          VMDK version 6 image
subformat        VMDK flat extent format, can be one of {monolithicSparse \
    (default) | monolithicFlat | twoGbMaxExtentSparse | twoGbMaxExtentFlat}
scsi             SCSI image

28.2.2.3 qemu-img check

Use qemu-img check to check the existing disk image for errors. Not all disk image formats support this feature. The command uses the following syntax:

tux > qemu-img check -f fmt1 fname2

1

The format of the source disk image. It is usually autodetected and can therefore be omitted.

2

Path to the source disk image to be checked.

If no error is found, the command returns no output. Otherwise, the type and number of errors found is shown.

tux > qemu-img check -f qcow2 /images/sles.qcow2
ERROR: invalid cluster offset=0x2af0000
[...]
ERROR: invalid cluster offset=0x34ab0000
378 errors were found on the image.

28.2.2.4 Increasing the Size of an Existing Disk Image

When creating a new image, you must specify its maximum size before the image is created (see Section 28.2.2.1, “qemu-img create”). After you have installed the VM Guest and have been using it for some time, the initial size of the image may no longer be sufficient. In that case, add more space to it.

To increase the size of an existing disk image by 2 gigabytes, use:

tux > qemu-img resize /images/sles.raw +2GB
Note
Note

You can resize the disk image using the formats raw, qcow2 and qed. To resize an image in another format, convert it to a supported format with qemu-img convert first.

The image now contains an empty space of 2 GB after the final partition. You can resize the existing partitions or add new ones.

New 2 GB Partition in Guest YaST Partitioner
Figure 28.1: New 2 GB Partition in Guest YaST Partitioner

28.2.2.5 Advanced Options for the qcow2 File Format

qcow2 is the main disk image format used by QEMU. Its size grows on demand, and the disk space is only allocated when it is actually needed by the virtual machine.

A qcow2 formatted file is organized in units of constant size. These units are called clusters. Viewed from the guest side, the virtual disk is also divided into clusters of the same size. QEMU defaults to 64 kB clusters, but you can specify a different value when creating a new image:

tux > qemu-img create -f qcow2 -o cluster_size=128K virt_disk.qcow2 4G

A qcow2 image contains a set of tables organized in two levels that are called the L1 and L2 tables. There is just one L1 table per disk image, while there can be many L2 tables depending on how big the image is.

To read or write data to the virtual disk, QEMU needs to read its corresponding L2 table to find out the relevant data location. Because reading the table for each I/O operation consumes system resources, QEMU keeps a cache of L2 tables in memory to speed up disk access.

28.2.2.5.1 Choosing the Right Cache Size

The cache size relates to the amount of allocated space. L2 cache can map the following amount of virtual disk:

disk_size = l2_cache_size * cluster_size / 8

With the default 64 kB of cluster size, that is

disk_size = l2_cache_size * 8192

Therefore, to have a cache that maps n gigabytes of disk space with the default cluster size, you need

l2_cache_size = disk_size_GB * 131072

QEMU uses 1 MB (1048576 bytes) of L2 cache by default. Following the above formulas, 1 MB of L2 cache covers 8 GB (1048576 / 131072) of virtual disk. This means that the performance is fine with the default L2 cache size if your virtual disk size is up to 8 GB. For larger disks, you can speed up the disk access by increasing the L2 cache size.

28.2.2.5.2 Configuring the Cache Size

You can use the -drive option on the QEMU command line to specify the cache sizes. Alternatively when communicating via QMP, use the blockdev-add command. For more information on QMP, see Section 30.11, “QMP - QEMU Machine Protocol”.

The following options configure the cache size for the virtual guest:

l2-cache-size

The maximum size of the L2 table cache.

refcount-cache-size

The maximum size of the refcount block cache. For more information on refcount, see https://github.com/qemu/qemu/blob/master/docs/specs/qcow2.txt.

cache-size

The maximum size of both caches combined.

When specifying values for the options above, be aware of the following:

  • The size of both the L2 and refcount block caches needs to be a multiple of the cluster size.

  • If you only set one of the options, QEMU will automatically adjust the other options so that the L2 cache is 4 times bigger than the refcount cache.

The refcount cache is used much less often than the L2 cache, therefore you can keep it relatively small:

root # qemu-system-ARCH [...] \
 -drive file=disk_image.qcow2,l2-cache-size=4194304,refcount-cache-size=262144
28.2.2.5.3 Reducing the Memory Usage

The larger the cache, the more memory it consumes. There is a separate L2 cache for each qcow2 file. When using a lot of big disk images, you will probably need a considerably large amount of memory. Memory consumption is even worse if you add backing files (Section 28.2.4, “Manipulate Disk Images Effectively”) and snapshots (see Section 28.2.3, “Managing Snapshots of Virtual Machines with qemu-img”) to the guest's setup chain.

That is why QEMU introduced the cache-clean-interval setting. It defines an interval in seconds after which all cache entries that have not been accessed are removed from memory.

The following example removes all unused cache entries every 10 minutes:

root # qemu-system-ARCH [...] -drive file=hd.qcow2,cache-clean-interval=600

If this option is not set, the default value is 0 and it disables this feature.

28.2.3 Managing Snapshots of Virtual Machines with qemu-img

Virtual Machine snapshots are snapshots of the complete environment in which a VM Guest is running. The snapshot includes the state of the processor (CPU), memory (RAM), devices, and all writable disks.

Snapshots are helpful when you need to save your virtual machine in a particular state. For example, after you configured network services on a virtualized server and want to quickly start the virtual machine in the same state you last saved it. Or you can create a snapshot after the virtual machine has been powered off to create a backup state before you try something experimental and possibly make VM Guest unstable. This section introduces the latter case, while the former is described in Chapter 30, Virtual Machine Administration Using QEMU Monitor.

To use snapshots, your VM Guest must contain at least one writable hard disk image in qcow2 format. This device is usually the first virtual hard disk.

Virtual Machine snapshots are created with the savevm command in the interactive QEMU monitor. To make identifying a particular snapshot easier, you can assign it a tag. For more information on QEMU monitor, see Chapter 30, Virtual Machine Administration Using QEMU Monitor.

Once your qcow2 disk image contains saved snapshots, you can inspect them with the qemu-img snapshot command.

Warning
Warning: Shut Down the VM Guest

Do not create or delete virtual machine snapshots with the qemu-img snapshot command while the virtual machine is running. Otherwise, you may damage the disk image with the state of the virtual machine saved.

28.2.3.1 Listing Existing Snapshots

Use qemu-img snapshot -l DISK_IMAGE to view a list of all existing snapshots saved in the disk_image image. You can get the list even while the VM Guest is running.

tux > qemu-img snapshot -l /images/sles.qcow2
Snapshot list:
ID1       TAG2               VM SIZE3        DATE4          VM CLOCK5
1         booting                4.4M 2013-11-22 10:51:10   00:00:20.476
2         booted                 184M 2013-11-22 10:53:03   00:02:05.394
3         logged_in              273M 2013-11-22 11:00:25   00:04:34.843
4         ff_and_term_running    372M 2013-11-22 11:12:27   00:08:44.965

1

Unique identification number of the snapshot. Usually auto-incremented.

2

Unique description string of the snapshot. It is meant as a human-readable version of the ID.

3

The disk space occupied by the snapshot. Note that the more memory is consumed by running applications, the bigger the snapshot is.

4

Time and date the snapshot was created.

5

The current state of the virtual machine's clock.

28.2.3.2 Creating Snapshots of a Powered-Off Virtual Machine

Use qemu-img snapshot -c SNAPSHOT_TITLE DISK_IMAGE to create a snapshot of the current state of a virtual machine that was previously powered off.

tux > qemu-img snapshot -c backup_snapshot /images/sles.qcow2
tux > qemu-img snapshot -l /images/sles.qcow2
Snapshot list:
ID        TAG                 VM SIZE                DATE       VM CLOCK
1         booting                4.4M 2013-11-22 10:51:10   00:00:20.476
2         booted                 184M 2013-11-22 10:53:03   00:02:05.394
3         logged_in              273M 2013-11-22 11:00:25   00:04:34.843
4         ff_and_term_running    372M 2013-11-22 11:12:27   00:08:44.965
5         backup_snapshot           0 2013-11-22 14:14:00   00:00:00.000

If something breaks in your VM Guest and you need to restore the state of the saved snapshot (ID 5 in our example), power off your VM Guest and execute the following command:

tux > qemu-img snapshot -a 5 /images/sles.qcow2

The next time you run the virtual machine with qemu-system-ARCH, it will be in the state of snapshot number 5.

Note
Note

The qemu-img snapshot -c command is not related to the savevm command of QEMU monitor (see Chapter 30, Virtual Machine Administration Using QEMU Monitor). For example, you cannot apply a snapshot with qemu-img snapshot -a on a snapshot created with savevm in QEMU's monitor.

28.2.3.3 Deleting Snapshots

Use qemu-img snapshot -d SNAPSHOT_ID DISK_IMAGE to delete old or unneeded snapshots of a virtual machine. This saves some disk space inside the qcow2 disk image as the space occupied by the snapshot data is restored:

tux > qemu-img snapshot -d 2 /images/sles.qcow2

28.2.4 Manipulate Disk Images Effectively

Imagine the following real-life situation: you are a server administrator who runs and manages several virtualized operating systems. One group of these systems is based on one specific distribution, while another group (or groups) is based on different versions of the distribution or even on a different (and maybe non-Unix) platform. To make the case even more complex, individual virtual guest systems based on the same distribution usually differ according to the department and deployment. A file server typically uses a different setup and services than a Web server does, while both may still be based on SUSE® Linux Enterprise Server.

With QEMU it is possible to create base disk images. You can use them as template virtual machines. These base images will save you plenty of time because you will never need to install the same operating system more than once.

28.2.4.1 Base and Derived Images

First, build a disk image as usual and install the target system on it. For more information, see Section 28.1, “Basic Installation with qemu-system-ARCH and Section 28.2.2, “Creating, Converting and Checking Disk Images”. Then build a new image while using the first one as a base image. The base image is also called a backing file. After your new derived image is built, never boot the base image again, but boot the derived image instead. Several derived images may depend on one base image at the same time. Therefore, changing the base image can damage the dependencies. While using your derived image, QEMU writes changes to it and uses the base image only for reading.

It is a good practice to create a base image from a freshly installed (and, if needed, registered) operating system with no patches applied and no additional applications installed or removed. Later on, you can create another base image with the latest patches applied and based on the original base image.

28.2.4.2 Creating Derived Images

Note
Note

While you can use the raw format for base images, you cannot use it for derived images because the raw format does not support the backing_file option. Use for example the qcow2 format for the derived images.

For example, /images/sles_base.raw is the base image holding a freshly installed system.

tux > qemu-img info /images/sles_base.raw
image: /images/sles_base.raw
file format: raw
virtual size: 4.0G (4294967296 bytes)
disk size: 2.4G

The image's reserved size is 4 GB, the actual size is 2.4 GB, and its format is raw. Create an image derived from the /images/sles_base.raw base image with:

tux > qemu-img create -f qcow2 /images/sles_derived.qcow2 \
-o backing_file=/images/sles_base.raw
Formatting '/images/sles_derived.qcow2', fmt=qcow2 size=4294967296 \
backing_file='/images/sles_base.raw' encryption=off cluster_size=0

Look at the derived image details:

tux > qemu-img info /images/sles_derived.qcow2
image: /images/sles_derived.qcow2
file format: qcow2
virtual size: 4.0G (4294967296 bytes)
disk size: 140K
cluster_size: 65536
backing file: /images/sles_base.raw \
(actual path: /images/sles_base.raw)

Although the reserved size of the derived image is the same as the size of the base image (4 GB), the actual size is 140 KB only. The reason is that only changes made to the system inside the derived image are saved. Run the derived virtual machine, register it, if needed, and apply the latest patches. Do any other changes in the system such as removing unneeded or installing new software packages. Then shut the VM Guest down and examine its details once more:

tux > qemu-img info /images/sles_derived.qcow2
image: /images/sles_derived.qcow2
file format: qcow2
virtual size: 4.0G (4294967296 bytes)
disk size: 1.1G
cluster_size: 65536
backing file: /images/sles_base.raw \
(actual path: /images/sles_base.raw)

The disk size value has grown to 1.1 GB, which is the disk space occupied by the changes on the file system compared to the base image.

28.2.4.3 Rebasing Derived Images

After you have modified the derived image (applied patches, installed specific applications, changed environment settings, etc.), it reaches the desired state. At that point, you can merge the original base image and the derived image to create a new base image.

Your original base image (/images/sles_base.raw) holds a freshly installed system. It can be a template for new modified base images, while the new one can contain the same system as the first one plus all security and update patches applied, for example. After you have created this new base image, you can use it as a template for more specialized derived images as well. The new base image becomes independent of the original one. The process of creating base images from derived ones is called rebasing:

tux > qemu-img convert /images/sles_derived.qcow2 \
-O raw /images/sles_base2.raw

This command created the new base image /images/sles_base2.raw using the raw format.

tux > qemu-img info /images/sles_base2.raw
image: /images/sles11_base2.raw
file format: raw
virtual size: 4.0G (4294967296 bytes)
disk size: 2.8G

The new image is 0.4 gigabytes bigger than the original base image. It uses no backing file, and you can easily create new derived images based upon it. This lets you create a sophisticated hierarchy of virtual disk images for your organization, saving a lot of time and work.

28.2.4.4 Mounting an Image on a VM Host Server

It can be useful to mount a virtual disk image under the host system. It is strongly recommended to read Chapter 17, libguestfs and use dedicated tools to access a virtual machine image. However, if you need to do this manually, follow this guide.

Linux systems can mount an internal partition of a raw disk image using a loopback device. The first example procedure is more complex but more illustrative, while the second one is straightforward:

Procedure 28.1: Mounting Disk Image by Calculating Partition Offset
  1. Set a loop device on the disk image whose partition you want to mount.

    tux > losetup /dev/loop0 /images/sles_base.raw
  2. Find the sector size and the starting sector number of the partition you want to mount.

    tux > fdisk -lu /dev/loop0
    
    Disk /dev/loop0: 4294 MB, 4294967296 bytes
    255 heads, 63 sectors/track, 522 cylinders, total 8388608 sectors
    Units = sectors of 1 * 512 = 5121 bytes
    Disk identifier: 0x000ceca8
    
           Device Boot      Start         End      Blocks   Id  System
    /dev/loop0p1              63     1542239      771088+  82  Linux swap
    /dev/loop0p2   *     15422402    8385929     3421845   83  Linux

    1

    The disk sector size.

    2

    The starting sector of the partition.

  3. Calculate the partition start offset:

    sector_size * sector_start = 512 * 1542240 = 789626880

  4. Delete the loop and mount the partition inside the disk image with the calculated offset on a prepared directory.

    tux > losetup -d /dev/loop0
    tux > mount -o loop,offset=789626880 \
    /images/sles_base.raw /mnt/sles/
    tux > ls -l /mnt/sles/
    total 112
    drwxr-xr-x   2 root root  4096 Nov 16 10:02 bin
    drwxr-xr-x   3 root root  4096 Nov 16 10:27 boot
    drwxr-xr-x   5 root root  4096 Nov 16 09:11 dev
    [...]
    drwxrwxrwt  14 root root  4096 Nov 24 09:50 tmp
    drwxr-xr-x  12 root root  4096 Nov 16 09:16 usr
    drwxr-xr-x  15 root root  4096 Nov 16 09:22 var
  5. Copy one or more files onto the mounted partition and unmount it when finished.

    tux > cp /etc/X11/xorg.conf /mnt/sles/root/tmp
    tux > ls -l /mnt/sles/root/tmp
    tux > umount /mnt/sles/
Warning
Warning: Do not Write to Images Currently in Use

Never mount a partition of an image of a running virtual machine in a read-write mode. This could corrupt the partition and break the whole VM Guest.

29 Running Virtual Machines with qemu-system-ARCH

  • Filename: qemu_running_vms_qemukvm.xml
  • ID: cha.qemu.running

Once you have a virtual disk image ready (for more information on disk images, see Section 28.2, “Managing Disk Images with qemu-img), it is time to start the related virtual machine. Section 28.1, “Basic Installation with qemu-system-ARCH introduced simple commands to install and run a VM Guest. This chapter focuses on a more detailed explanation of qemu-system-ARCH usage, and shows solutions for more specific tasks. For a complete list of qemu-system-ARCH's options, see its manual page (man 1 qemu).

29.1 Basic qemu-system-ARCH Invocation

The qemu-system-ARCH command uses the following syntax:

qemu-system-ARCH options1 disk_img2

1

qemu-system-ARCH understands many options. Most of them define parameters of the emulated hardware, while others affect more general emulator behavior. If you do not supply any options, default values are used, and you need to supply the path to a disk image to be run.

2

Path to the disk image holding the guest system you want to virtualize. qemu-system-ARCH supports many image formats. Use qemu-img --help to list them. If you do not supply the path to a disk image as a separate argument, you need to use the -drive file= option.

29.2 General qemu-system-ARCH Options

This section introduces general qemu-system-ARCH options and options related to the basic emulated hardware, such as the virtual machine's processor, memory, model type, or time processing methods.

-name NAME_OF_GUEST

Specifies the name of the running guest system. The name is displayed in the window caption and used for the VNC server.

-boot OPTIONS

Specifies the order in which the defined drives will be booted. Drives are represented by letters, where a and b stand for the floppy drives 1 and 2, c stands for the first hard disk, d stands for the first CD-ROM drive, and n to p stand for Ether-boot network adapters.

For example, qemu-system-ARCH [...] -boot order=ndc first tries to boot from network, then from the first CD-ROM drive, and finally from the first hard disk.

-pidfile FILENAME

Stores the QEMU's process identification number (PID) in a file. This is useful if you run QEMU from a script.

-nodefaults

By default QEMU creates basic virtual devices even if you do not specify them on the command line. This option turns this feature off, and you must specify every single device manually, including graphical and network cards, parallel or serial ports, or virtual consoles. Even QEMU monitor is not attached by default.

-daemonize

Daemonizes the QEMU process after it is started. QEMU will detach from the standard input and standard output after it is ready to receive connections on any of its devices.

Note
Note: SeaBIOS BIOS Implementation

SeaBIOS is the default BIOS used. You can boot USB devices, any drive (CD-ROM, Floppy, or a hard disk). It has USB mouse and keyboard support and supports multiple VGA cards. For more information about SeaBIOS, refer to the SeaBIOS Website.

29.2.1 Basic Virtual Hardware

29.2.1.1 Machine Type

You can specifies the type of the emulated machine. Run qemu-system-ARCH -M help to view a list of supported machine types.

Note
Note: ISA-PC

The machine type isapc: ISA-only-PC is unsupported.

29.2.1.2 CPU Model

To specify the type of the processor (CPU) model, run qemu-system-ARCH -cpu MODEL. Use qemu-system-ARCH -cpu help to view a list of supported CPU models.

CPU flags information can be found at CPUID Wikipedia.

29.2.1.3 Other Basics Options

The following is a list of most commonly used options while launching qemu from command line. To see all options available refer to qemu-doc man page.

-m MEGABYTES

Specifies how many megabytes are used for the virtual RAM size.

-balloon virtio

Specifies a paravirtualized device to dynamically change the amount of virtual RAM memory assigned to VM Guest. The top limit is the amount of memory specified with -m.

-smp NUMBER_OF_CPUS

Specifies how many CPUs will be emulated. QEMU supports up to 255 CPUs on the PC platform (up to 64 with KVM acceleration used). This option also takes other CPU-related parameters, such as number of sockets, number of cores per socket, or number of threads per core.

The following is an example of a working qemu-system-ARCH command line:

tux > qemu-system-x86_64 -name "SLES 12 SP2" -M pc-i440fx-2.7 -m 512 \
-machine accel=kvm -cpu kvm64 -smp 2 -drive /images/sles.raw
QEMU Window with SLES 11 SP3 as VM Guest
Figure 29.1: QEMU Window with SLES 11 SP3 as VM Guest
-no-acpi

Disables ACPI support.

-S

QEMU starts with CPU stopped. To start CPU, enter c in QEMU monitor. For more information, see Chapter 30, Virtual Machine Administration Using QEMU Monitor.

29.2.2 Storing and Reading Configuration of Virtual Devices

-readconfig CFG_FILE

Instead of entering the devices configuration options on the command line each time you want to run VM Guest, qemu-system-ARCH can read it from a file that was either previously saved with -writeconfig or edited manually.

-writeconfig CFG_FILE

Dumps the current virtual machine's devices configuration to a text file. It can be consequently re-used with the -readconfig option.

tux > qemu-system-x86_64 -name "SLES 12 SP2" -machine accel=kvm -M pc-i440fx-2.7 -m 512 -cpu kvm64 \
-smp 2 /images/sles.raw -writeconfig /images/sles.cfg
(exited)
tux > cat /images/sles.cfg
# qemu config file

[drive]
  index = "0"
  media = "disk"
  file = "/images/sles_base.raw"

This way you can effectively manage the configuration of your virtual machines' devices in a well-arranged way.

29.2.3 Guest Real-Time Clock

-rtc OPTIONS

Specifies the way the RTC is handled inside a VM Guest. By default, the clock of the guest is derived from that of the host system. Therefore, it is recommended that the host system clock is synchronized with an accurate external clock (for example, via NTP service).

If you need to isolate the VM Guest clock from the host one, specify clock=vm instead of the default clock=host.

You can also specify the initial time of the VM Guest's clock with the base option:

qemu-system-x86_64 [...] -rtc clock=vm,base=2010-12-03T01:02:00

Instead of a time stamp, you can specify utc or localtime. The former instructs VM Guest to start at the current UTC value (Coordinated Universal Time, see http://en.wikipedia.org/wiki/UTC), while the latter applies the local time setting.

29.3 Using Devices in QEMU

QEMU virtual machines emulate all devices needed to run a VM Guest. QEMU supports, for example, several types of network cards, block devices (hard and removable drives), USB devices, character devices (serial and parallel ports), or multimedia devices (graphic and sound cards). This section introduces options to configure various types of supported devices.

Tip
Tip

If your device, such as -drive, needs a special driver and driver properties to be set, specify them with the -device option, and identify with drive= suboption. For example:

qemu-system-x86_64 [...] -drive if=none,id=drive0,format=raw \
-device virtio-blk-pci,drive=drive0,scsi=off ...

To get help on available drivers and their properties, use -device ? and -device DRIVER,?.

29.3.1 Block Devices

Block devices are vital for virtual machines. In general, these are fixed or removable storage media usually called drives. One of the connected hard disks typically holds the guest operating system to be virtualized.

Virtual Machine drives are defined with -drive. This option has many sub-options, some of which are described in this section. For the complete list, see the manual page (man 1 qemu).

Sub-options for the -drive Option
file=image_fname

Specifies the path to the disk image that will be used with this drive. If not specified, an empty (removable) drive is assumed.

if=drive_interface

Specifies the type of interface to which the drive is connected. Currently only floppy, scsi, ide, or virtio are supported by SUSE. virtio defines a paravirtualized disk driver. Default is ide.

index=index_of_connector

Specifies the index number of a connector on the disk interface (see the if option) where the drive is connected. If not specified, the index is automatically incremented.

media=type

Specifies the type of media. Can be disk for hard disks, or cdrom for removable CD-ROM drives.

format=img_fmt

Specifies the format of the connected disk image. If not specified, the format is autodetected. Currently, SUSE supports qcow2, qed and raw formats.

cache=method

Specifies the caching method for the drive. Possible values are unsafe, writethrough, writeback, directsync, or none. To improve performance when using the qcow2 image format, select writeback. none disables the host page cache and, therefore, is the safest option. Default for image files is writeback. For more information, see Chapter 15, Disk Cache Modes.

Tip
Tip

To simplify defining block devices, QEMU understands several shortcuts which you may find handy when entering the qemu-system-ARCH command line.

You can use

qemu-system-x86_64 -cdrom /images/cdrom.iso

instead of

qemu-system-x86_64 -drive file=/images/cdrom.iso,index=2,media=cdrom

and

qemu-system-x86_64 -hda /images/imagei1.raw -hdb /images/image2.raw -hdc \
/images/image3.raw -hdd /images/image4.raw

instead of

qemu-system-x86_64 -drive file=/images/image1.raw,index=0,media=disk \
-drive file=/images/image2.raw,index=1,media=disk \
-drive file=/images/image3.raw,index=2,media=disk \
-drive file=/images/image4.raw,index=3,media=disk
Tip
Tip: Using Host Drives Instead of Images

As an alternative to using disk images (see Section 28.2, “Managing Disk Images with qemu-img) you can also use existing VM Host Server disks, connect them as drives, and access them from VM Guest. Use the host disk device directly instead of disk image file names.

To access the host CD-ROM drive, use

qemu-system-x86_64 [...] -drive file=/dev/cdrom,media=cdrom

To access the host hard disk, use

qemu-system-x86_64 [...] -drive file=/dev/hdb,media=disk

A host drive used by a VM Guest must not be accessed concurrently by the VM Host Server or another VM Guest.

29.3.1.1 Freeing Unused Guest Disk Space

A Sparse image file is a type of disk image file that grows in size as the user adds data to it, taking up only as much disk space as is stored in it. For example, if you copy 1 GB of data inside the sparse disk image, its size grows by 1 GB. If you then delete for example 500 MB of the data, the image size does not by default decrease as expected.

That is why the discard=on option is introduced on the KVM command line. It tells the hypervisor to automatically free the holes after deleting data from the sparse guest image. Note that this option is valid only for the if=scsi drive interface:

qemu-system-x86_64 [...] -drive file=/path/to/file.img,if=scsi,discard=on
Important
Important: Support Status

if=scsi is not supported. This interface does not map to virtio-scsi, but rather to the lsi SCSI adapter.

29.3.1.2 IOThreads

IOThreads are dedicated event loop threads for virtio devices to perform I/O requests in order to improve scalability, especially on an SMP VM Host Server with SMP VM Guests using many disk devices. Instead of using QEMU's main event loop for I/O processing, IOThreads allow spreading I/O work across multiple CPUs and can improve latency when properly configured.

IOThreads are enabled by defining IOThread objects. virtio devices can then use the objects for their I/0 event loops. Many virtio devices can use a single IOThread object, or virtio devices and IOThread objects can be configured in a 1:1 mapping. The following example creates a single IOThread with ID iothread0 which is then used as the event loop for two virtio-blk devices.

tux > qemu-system-x86_64 [...] -object iothread,id=iothread0\
-drive if=none,id=drive0,cache=none,aio=native,\
format=raw,file=filename -device virtio-blk-pci,drive=drive0,scsi=off,\
iothread=iothread0 -drive if=none,id=drive1,cache=none,aio=native,\
format=raw,file=filename -device virtio-blk-pci,drive=drive1,scsi=off,\
iothread=iothread0 [...]

The following qemu command line example illustrates a 1:1 virtio device to IOThread mapping:

tux > qemu-system-x86_64 [...] -object iothread,id=iothread0\
-object iothread,id=iothread1 -drive if=none,id=drive0,cache=none,aio=native,\
format=raw,file=filename -device virtio-blk-pci,drive=drive0,scsi=off,\
iothread=iothread0 -drive if=none,id=drive1,cache=none,aio=native,\
format=raw,file=filename -device virtio-blk-pci,drive=drive1,scsi=off,\
    iothread=iothread1 [...]

29.3.1.3 Bio-Based I/O Path for virtio-blk

For better performance of I/O-intensive applications, a new I/O path was introduced for the virtio-blk interface in kernel version 3.7. This bio-based block device driver skips the I/O scheduler, and thus shortens the I/O path in guest and has lower latency. It is especially useful for high-speed storage devices, such as SSD disks.

The driver is disabled by default. To use it, do the following:

  1. Append virtio_blk.use_bio=1 to the kernel command line on the guest. You can do so via YaST › System › Boot Loader.

    You can do it also by editing /etc/default/grub, searching for the line that contains GRUB_CMDLINE_LINUX_DEFAULT=, and adding the kernel parameter at the end. Then run grub2-mkconfig >/boot/grub2/grub.cfg to update the grub2 boot menu.

  2. Reboot the guest with the new kernel command line active.

Tip
Tip: Bio-Based Driver on Slow Devices

The bio-based virtio-blk driver does not help on slow devices such as spin hard disks. The reason is that the benefit of scheduling is larger than what the shortened bio path offers. Do not use the bio-based driver on slow devices.

29.3.1.4 Accessing iSCSI Resources Directly

QEMU now integrates with libiscsi. This allows QEMU to access iSCSI resources directly and use them as virtual machine block devices. This feature does not require any host iSCSI initiator configuration, as is needed for a libvirt iSCSI target based storage pool setup. Instead it directly connects guest storage interfaces to an iSCSI target LUN by means of the user space library libiscsi. iSCSI-based disk devices can also be specified in the libvirt XML configuration.

Note
Note: RAW Image Format

This feature is only available using the RAW image format, as the iSCSI protocol has some technical limitations.

The following is the QEMU command line interface for iSCSI connectivity.

Note
Note: virt-manager Limitation

The use of libiscsi based storage provisioning is not yet exposed by the virt-manager interface, but instead it would be configured by directly editing the guest xml. This new way of accessing iSCSI based storage is to be done at the command line.

qemu-system-x86_64 -machine accel=kvm \
  -drive file=iscsi://192.168.100.1:3260/iqn.2016-08.com.example:314605ab-a88e-49af-b4eb-664808a3443b/0,\
  format=raw,if=none,id=mydrive,cache=none \
  -device ide-hd,bus=ide.0,unit=0,drive=mydrive ...

Here is an example snippet of guest domain xml which uses the protocol based iSCSI:

<devices>
...
  <disk type='network' device='disk'>
    <driver name='qemu' type='raw'/>
    <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/2'>
      <host name='example.com' port='3260'/>
    </source>
    <auth username='myuser'>
      <secret type='iscsi' usage='libvirtiscsi'/>
    </auth>
    <target dev='vda' bus='virtio'/>
  </disk>
</devices>

Contrast that with an example which uses the host based iSCSI initiator which virt-manager sets up:

<devices>
...
  <disk type='block' device='disk'>
    <driver name='qemu' type='raw' cache='none' io='native'/>
    <source dev='/dev/disk/by-path/scsi-0:0:0:0'/>
    <target dev='hda' bus='ide'/>
    <address type='drive' controller='0' bus='0' target='0' unit='0'/>
  </disk>
  <controller type='ide' index='0'>
    <address type='pci' domain='0x0000' bus='0x00' slot='0x01'
             function='0x1'/>
  </controller>
</devices>

29.3.1.5 Using RADOS Block Devices with QEMU

RADOS Block Devices (RBD) store data in a Ceph cluster. They allow snapshotting, replication, and data consistency. You can use an RBD from your KVM-managed VM Guests similarly you use other block devices.

Refer to SUSE Enterprise Storage documentation for more details.

29.3.2 Graphic Devices and Display Options

This section describes QEMU options affecting the type of the emulated video card and the way VM Guest graphical output is displayed.

29.3.2.1 Defining Video Cards

QEMU uses -vga to define a video card used to display VM Guest graphical output. The -vga option understands the following values:

none

Disables video cards on VM Guest (no video card is emulated). You can still access the running VM Guest via the serial console.

std

Emulates a standard VESA 2.0 VBE video card. Use it if you intend to use high display resolution on VM Guest.

cirrus

Emulates Cirrus Logic GD5446 video card. Good choice if you insist on high compatibility of the emulated video hardware. Most operating systems (even Windows 95) recognize this type of card.

Tip
Tip

For best video performance with the cirrus type, use 16-bit color depth both on VM Guest and VM Host Server.

29.3.2.2 Display Options

The following options affect the way VM Guest graphical output is displayed.

-display gtk

Display video output in a GTK window. This interface provides UI elements to configure and control the VM during runtime.

-display sdl

Display video output via SDL, usually in a separate graphics window. For more information, see the SDL documentation.

-spice option[,option[,...]]

Enables the spice remote desktop protocol.

-display vnc

Refer to Section 29.5, “Viewing a VM Guest with VNC” for more information.

-nographic

Disables QEMU's graphical output. The emulated serial port is redirected to the console.

After starting the virtual machine with -nographic, press CtrlA H in the virtual console to view the list of other useful shortcuts, for example, to toggle between the console and the QEMU monitor.

tux > qemu-system-x86_64 -hda /images/sles_base.raw -nographic

C-a h    print this help
C-a x    exit emulator
C-a s    save disk data back to file (if -snapshot)
C-a t    toggle console timestamps
C-a b    send break (magic sysrq)
C-a c    switch between console and monitor
C-a C-a  sends C-a
(pressed C-a c)

QEMU 2.3.1 monitor - type 'help' for more information
(qemu)
-no-frame

Disables decorations for the QEMU window. Convenient for dedicated desktop work space.

-full-screen

Starts QEMU graphical output in full screen mode.

-no-quit

Disables the close button of the QEMU window and prevents it from being closed by force.

-alt-grab, -ctrl-grab

By default, the QEMU window releases the captured mouse after pressing CtrlAlt. You can change the key combination to either CtrlAltShift (-alt-grab), or the right Ctrl key (-ctrl-grab).

29.3.3 USB Devices

There are two ways to create USB devices usable by the VM Guest in KVM: you can either emulate new USB devices inside a VM Guest, or assign an existing host USB device to a VM Guest. To use USB devices in QEMU you first need to enable the generic USB driver with the -usb option. Then you can specify individual devices with the -usbdevice option.

29.3.3.1 Emulating USB Devices in VM Guest

SUSE currently supports the following types of USB devices: disk, host, serial, braille, net, mouse, and tablet.

Types of USB devices for the -usbdevice option
disk

Emulates a mass storage device based on file. The optional format option is used rather than detecting the format.

qemu-system-x86_64 [...] -usbdevice
        disk:format=raw:/virt/usb_disk.raw
host

Pass through the host device (identified by bus.addr).

serial

Serial converter to a host character device.

braille

Emulates a braille device using BrlAPI to display the braille output.

net

Emulates a network adapter that supports CDC Ethernet and RNDIS protocols.

mouse

Emulates a virtual USB mouse. This option overrides the default PS/2 mouse emulation. The following example shows the hardware status of a mouse on VM Guest started with qemu-system-ARCH [...] -usbdevice mouse:

tux > sudo hwinfo --mouse
20: USB 00.0: 10503 USB Mouse
[Created at usb.122]
UDI: /org/freedesktop/Hal/devices/usb_device_627_1_1_if0
[...]
Hardware Class: mouse
Model: "Adomax QEMU USB Mouse"
Hotplug: USB
Vendor: usb 0x0627 "Adomax Technology Co., Ltd"
Device: usb 0x0001 "QEMU USB Mouse"
[...]
tablet

Emulates a pointer device that uses absolute coordinates (such as touchscreen). This option overrides the default PS/2 mouse emulation. The tablet device is useful if you are viewing VM Guest via the VNC protocol. See Section 29.5, “Viewing a VM Guest with VNC” for more information.

29.3.4 Character Devices

Use -chardev to create a new character device. The option uses the following general syntax:

qemu-system-x86_64 [...] -chardev BACKEND_TYPE,id=ID_STRING

where BACKEND_TYPE can be one of null, socket, udp, msmouse, vc, file, pipe, console, serial, pty, stdio, braille, tty, or parport. All character devices must have a unique identification string up to 127 characters long. It is used to identify the device in other related directives. For the complete description of all back-end's sub-options, see the manual page (man 1 qemu). A brief description of the available back-ends follows:

null

Creates an empty device that outputs no data and drops any data it receives.

stdio

Connects to QEMU's process standard input and standard output.

socket

Creates a two-way stream socket. If PATH is specified, a Unix socket is created:

qemu-system-x86_64 [...] -chardev \
socket,id=unix_socket1,path=/tmp/unix_socket1,server

The SERVER suboption specifies that the socket is a listening socket.

If PORT is specified, a TCP socket is created:

qemu-system-x86_64 [...] -chardev \
socket,id=tcp_socket1,host=localhost,port=7777,server,nowait

The command creates a local listening (server) TCP socket on port 7777. QEMU will not block waiting for a client to connect to the listening port (nowait).

udp

Sends all network traffic from VM Guest to a remote host over the UDP protocol.

qemu-system-x86_64 [...] \
-chardev udp,id=udp_fwd,host=mercury.example.com,port=7777

The command binds port 7777 on the remote host mercury.example.com and sends VM Guest network traffic there.

vc

Creates a new QEMU text console. You can optionally specify the dimensions of the virtual console:

qemu-system-x86_64 [...] -chardev vc,id=vc1,width=640,height=480 \
-mon chardev=vc1

The command creates a new virtual console called vc1 of the specified size, and connects the QEMU monitor to it.

file

Logs all traffic from VM Guest to a file on VM Host Server. The path is required and will be created if it does not exist.

qemu-system-x86_64 [...] \
-chardev file,id=qemu_log1,path=/var/log/qemu/guest1.log

By default QEMU creates a set of character devices for serial and parallel ports, and a special console for QEMU monitor. However, you can create your own character devices and use them for the mentioned purposes. The following options will help you:

-serial CHAR_DEV

Redirects the VM Guest's virtual serial port to a character device CHAR_DEV on VM Host Server. By default, it is a virtual console (vc) in graphical mode, and stdio in non-graphical mode. The -serial understands many sub-options. See the manual page man 1 qemu for a complete list of them.

You can emulate up to 4 serial ports. Use -serial none to disable all serial ports.

-parallel DEVICE

Redirects the VM Guest's parallel port to a DEVICE. This option supports the same devices as -serial.

Tip
Tip

With SUSE Linux Enterprise Server as a VM Host Server, you can directly use the hardware parallel port devices /dev/parportN where N is the number of the port.

You can emulate up to 3 parallel ports. Use -parallel none to disable all parallel ports.

-monitor CHAR_DEV

Redirects the QEMU monitor to a character device CHAR_DEV on VM Host Server. This option supports the same devices as -serial. By default, it is a virtual console (vc) in a graphical mode, and stdio in non-graphical mode.

For a complete list of available character devices back-ends, see the man page (man 1 qemu).

29.4 Networking in QEMU

Use the -netdev option in combination with -device to define a specific type of networking and a network interface card for your VM Guest. The syntax for the -netdev option is

-netdev type[,prop[=value][,...]]

Currently, SUSE supports the following network types: user, bridge, and tap. For a complete list of -netdev sub-options, see the manual page (man 1 qemu).

Supported -netdev Sub-options
bridge

Uses a specified network helper to configure the TAP interface and attach it to a specified bridge. For more information, see Section 29.4.3, “Bridged Networking”.

user

Specifies user-mode networking. For more information, see Section 29.4.2, “User-Mode Networking”.

tap

Specifies bridged or routed networking. For more information, see Section 29.4.3, “Bridged Networking”.

29.4.1 Defining a Network Interface Card

Use -netdev together with the related -device option to add a new emulated network card:

qemu-system-x86_64 [...] \
-netdev tap1,id=hostnet0 \
-device virtio-net-pci2,netdev=hostnet0,vlan=13,\
macaddr=00:16:35:AF:94:4B4,name=ncard1

1

Specifies the network device type.

2

Specifies the model of the network card. Use qemu-system-ARCH -device help and search for the Network devices:section to get the list of all network card models supported by QEMU on your platform.

Currently, SUSE supports the models rtl8139, e1000 and its variants e1000-82540em, e1000-82544gc and e1000-82545em, and virtio-net-pci. To view a list of options for a specific driver, add help as a driver option:

qemu-system-x86_64 -device e1000,help
e1000.mac=macaddr
e1000.vlan=vlan
e1000.netdev=netdev
e1000.bootindex=int32
e1000.autonegotiation=on/off
e1000.mitigation=on/off
e1000.addr=pci-devfn
e1000.romfile=str
e1000.rombar=uint32
e1000.multifunction=on/off
e1000.command_serr_enable=on/off

3

Connects the network interface to VLAN number 1. You can specify your own number—it is mainly useful for identification purpose. If you omit this suboption, QEMU uses the default 0.

4

Specifies the Media Access Control (MAC) address for the network card. It is a unique identifier and you are advised to always specify it. If not, QEMU supplies its own default MAC address and creates a possible MAC address conflict within the related VLAN.

29.4.2 User-Mode Networking

The -netdev user option instructs QEMU to use user-mode networking. This is the default if no networking mode is selected. Therefore, these command lines are equivalent:

qemu-system-x86_64 -hda /images/sles_base.raw
qemu-system-x86_64 -hda /images/sles_base.raw -netdev user,id=hostnet0

This mode is useful if you want to allow the VM Guest to access the external network resources, such as the Internet. By default, no incoming traffic is permitted and therefore, the VM Guest is not visible to other machines on the network. No administrator privileges are required in this networking mode. The user-mode is also useful for doing a network boot on your VM Guest from a local directory on VM Host Server.

The VM Guest allocates an IP address from a virtual DHCP server. VM Host Server (the DHCP server) is reachable at 10.0.2.2, while the IP address range for allocation starts from 10.0.2.15. You can use ssh to connect to VM Host Server at 10.0.2.2, and scp to copy files back and forth.

29.4.2.1 Command Line Examples

This section shows several examples on how to set up user-mode networking with QEMU.

Example 29.1: Restricted User-mode Networking
qemu-system-x86_64 [...] \
-netdev user1,id=hostnet0 \
-device virtio-net-pci,netdev=hostnet0,vlan=12,name=user_net13,restrict=yes4

1

Specifies user-mode networking.

2

Connects to VLAN number 1. If omitted, defaults to 0.

3

Specifies a human-readable name of the network stack. Useful when identifying it in the QEMU monitor.

4

Isolates VM Guest. It then cannot communicate with VM Host Server and no network packets will be routed to the external network.

Example 29.2: User-mode Networking with Custom IP Range
qemu-system-x86_64 [...] \
-netdev user,id=hostnet0 \
-device virtio-net-pci,netdev=hostnet0,net=10.2.0.0/81,host=10.2.0.62,\
dhcpstart=10.2.0.203,hostname=tux_kvm_guest4

1

Specifies the IP address of the network that VM Guest sees and optionally the netmask. Default is 10.0.2.0/8.

2

Specifies the VM Host Server IP address that VM Guest sees. Default is 10.0.2.2.

3

Specifies the first of the 16 IP addresses that the built-in DHCP server can assign to VM Guest. Default is 10.0.2.15.

4

Specifies the host name that the built-in DHCP server will assign to VM Guest.

Example 29.3: User-mode Networking with Network-boot and TFTP
qemu-system-x86_64 [...] \
-netdev user,id=hostnet0 \
-device virtio-net-pci,netdev=hostnet0,tftp=/images/tftp_dir1,\
bootfile=/images/boot/pxelinux.02

1

Activates a built-in TFTP (a file transfer protocol with the functionality of a very basic FTP) server. The files in the specified directory will be visible to a VM Guest as the root of a TFTP server.

2

Broadcasts the specified file as a BOOTP (a network protocol that offers an IP address and a network location of a boot image, often used in diskless workstations) file. When used together with tftp, the VM Guest can boot from network from the local directory on the host.

Example 29.4: User-mode Networking with Host Port Forwarding
qemu-system-x86_64 [...] \
-netdev user,id=hostnet0 \
-device virtio-net-pci,netdev=hostnet0,hostfwd=tcp::2222-:22

Forwards incoming TCP connections to the port 2222 on the host to the port 22 (SSH) on VM Guest. If sshd is running on VM Guest, enter

ssh qemu_host -p 2222

where qemu_host is the host name or IP address of the host system, to get a SSH prompt from VM Guest.

29.4.3 Bridged Networking

With the -netdev tap option, QEMU creates a network bridge by connecting the host TAP network device to a specified VLAN of VM Guest. Its network interface is then visible to the rest of the network. This method does not work by default and needs to be explicitly specified.

First, create a network bridge and add a VM Host Server physical network interface (usually eth0) to it:

  1. Start YaST Control Center and select System › Network Settings.

  2. Click Add and select Bridge from the Device Type drop-down box in the Hardware Dialog window. Click Next.

  3. Choose whether you need a dynamically or statically assigned IP address, and fill the related network settings if applicable.

  4. In the Bridged Devices pane, select the Ethernet device to add to the bridge.

    Configuring Network Bridge with YaST
    Figure 29.2: Configuring Network Bridge with YaST

    Click Next. When asked about adapting an already configured device, click Continue.

  5. Click OK to apply the changes. Check if the bridge is created:

    tux > brctl show
    bridge name bridge id          STP enabled  interfaces
    br0         8000.001676d670e4  no           eth0

29.4.3.1 Connecting to a Bridge Manually

Use the following example script to connect VM Guest to the newly created bridge interface br0. Several commands in the script are run via the sudo mechanism because they require root privileges.

Note
Note: Required Packages

Make sure the tunctl and bridge-utils packages are installed on the VM Host Server. If not, install them with zypper in tunctl bridge-utils.

#!/bin/bash
bridge=br01
tap=$(sudo tunctl -u $(whoami) -b)2
sudo ip link set $tap up3
sleep 1s4
sudo brctl addif $bridge $tap5
qemu-system-x86_64 -machine accel=kvm -m 512 -hda /images/sles_base.raw \
-netdev tap,id=hostnet0 \
-device virtio-net-pci,netdev=hostnet0,vlan=0,macaddr=00:16:35:AF:94:4B,\
ifname=$tap6,script=no7,downscript=no
sudo brctl delif $bridge $tap8
sudo ip link set $tap down9
sudo tunctl -d $tap10

1

Name of the bridge device.

2

Prepare a new TAP device and assign it to the user who runs the script. TAP devices are virtual network devices often used for virtualization and emulation setups.

3

Bring up the newly created TAP network interface.

4

Make a 1-second pause to make sure the new TAP network interface is really up.

5

Add the new TAP device to the network bridge br0.

6

The ifname= suboption specifies the name of the TAP network interface used for bridging.

7

Before qemu-system-ARCH connects to a network bridge, it checks the script and downscript values. If it finds the specified scripts on the VM Host Server file system, it runs the script before it connects to the network bridge and downscript after it exits the network environment. You can use these scripts to first set up and bring up the bridged network devices, and then to deconfigure them. By default, /etc/qemu-ifup and /etc/qemu-ifdown are examined. If script=no and downscript=no are specified, the script execution is disabled and you need to take care of it manually.

8

Deletes the TAP interface from a network bridge br0.

9

Sets the state of the TAP device to down.

10

Deconfigures the TAP device.

29.4.3.2 Connecting to a Bridge with qemu-bridge-helper

Another way to connect VM Guest to a network through a network bridge is by means of the qemu-bridge-helper helper program. It configures the TAP interface for you, and attaches it to the specified bridge. The default helper executable is /usr/lib/qemu-bridge-helper. The helper executable is setuid root, which is only executable by the members of the virtualization group (kvm). Therefore the qemu-system-ARCH command itself does not need to be run under root privileges.

The helper is automatically called when you specify a network bridge:

qemu-system-x86_64 [...] \
 -netdev bridge,id=hostnet0,vlan=0,br=br0 \
 -device virtio-net-pci,netdev=hostnet0

You can specify your own custom helper script that will take care of the TAP device (de)configuration, with the helper=/path/to/your/helper option:

qemu-system-x86_64 [...] \
 -netdev bridge,id=hostnet0,vlan=0,br=br0,helper=/path/to/bridge-helper \
 -device virtio-net-pci,netdev=hostnet0
Tip
Tip

To define access privileges to qemu-bridge-helper, inspect the /etc/qemu/bridge.conf file. For example the following directive

allow br0

allows the qemu-system-ARCH command to connect its VM Guest to the network bridge br0.

29.5 Viewing a VM Guest with VNC

By default QEMU uses a GTK (a cross-platform toolkit library) window to display the graphical output of a VM Guest. With the -vnc option specified, you can make QEMU listen on a specified VNC display and redirect its graphical output to the VNC session.

Tip
Tip

When working with QEMU's virtual machine via VNC session, it is useful to work with the -usbdevice tablet option.

Moreover, if you need to use another keyboard layout than the default en-us, specify it with the -k option.

The first suboption of -vnc must be a display value. The -vnc option understands the following display specifications:

host:display

Only connections from host on the display number display will be accepted. The TCP port on which the VNC session is then running is normally a 5900 + display number. If you do not specify host, connections will be accepted from any host.

unix:path

The VNC server listens for connections on Unix domain sockets. The path option specifies the location of the related Unix socket.

none

The VNC server functionality is initialized, but the server itself is not started. You can start the VNC server later with the QEMU monitor. For more information, see Chapter 30, Virtual Machine Administration Using QEMU Monitor.

Following the display value there may be one or more option flags separated by commas. Valid options are:

reverse

Connect to a listening VNC client via a reverse connection.

websocket

Opens an additional TCP listening port dedicated to VNC Websocket connections. By definition the Websocket port is 5700+display.

password

Require that password-based authentication is used for client connections.

tls

Require that clients use TLS when communicating with the VNC server.

x509=/path/to/certificate/dir

Valid if TLS is specified. Require that x509 credentials are used for negotiating the TLS session.

x509verify=/path/to/certificate/dir

Valid if TLS is specified. Require that x509 credentials are used for negotiating the TLS session.

sasl

Require that the client uses SASL to authenticate with the VNC server.

acl

Turn on access control lists for checking of the x509 client certificate and SASL party.

lossy

Enable lossy compression methods (gradient, JPEG, ...).

non-adaptive

Disable adaptive encodings. Adaptive encodings are enabled by default.

share=[allow-exclusive|force-shared|ignore]

Set display sharing policy.

Note
Note

For more details about the display options, see the qemu-doc man page.

An example VNC usage:

tux > qemu-system-x86_64 [...] -vnc :5
(on the client:)
wilber > :~>vinagre venus:5905 &
QEMU VNC Session
Figure 29.3: QEMU VNC Session

29.5.1 Secure VNC Connections

The default VNC server setup does not use any form of authentication. In the previous example, any user can connect and view the QEMU VNC session from any host on the network.

There are several levels of security that you can apply to your VNC client/server connection. You can either protect your connection with a password, use x509 certificates, use SASL authentication, or even combine some authentication methods in one QEMU command.

See Section B.2, “Generating x509 Client/Server Certificates” for more information about the x509 certificates generation. For more information about configuring x509 certificates on a VM Host Server and the client, see Section 11.3.2, “Remote TLS/SSL Connection with x509 Certificate (qemu+tls or xen+tls)” and Section 11.3.2.3, “Configuring the Client and Testing the Setup”.

The Vinagre VNC viewer supports advanced authentication mechanisms. Therefore, it will be used to view the graphical output of VM Guest in the following examples. For this example, let us assume that the server x509 certificates ca-cert.pem, server-cert.pem, and server-key.pem are located in the /etc/pki/qemu directory on the host, while the client's certificates are distributed in the following locations on the client:

/etc/pki/CA/cacert.pem
/etc/pki/libvirt-vnc/clientcert.pem
/etc/pki/libvirt-vnc/private/clientkey.pem
Example 29.5: Password Authentication
qemu-system-x86_64 [...] -vnc :5,password -monitor stdio

Starts the VM Guest graphical output on VNC display number 5 (usually port 5905). The password suboption initializes a simple password-based authentication method. There is no password set by default and you need to set one with the change vnc password command in QEMU monitor:

QEMU 2.3.1 monitor - type 'help' for more information
(qemu) change vnc password
Password: ****

You need the -monitor stdio option here, because you would not be able to manage the QEMU monitor without redirecting its input/output.

Authentication Dialog in Vinagre
Figure 29.4: Authentication Dialog in Vinagre
Example 29.6: x509 Certificate Authentication

The QEMU VNC server can use TLS encryption for the session and x509 certificates for authentication. The server asks the client for a certificate and validates it against the CA certificate. Use this authentication type if your company provides an internal certificate authority.

qemu-system-x86_64 [...] -vnc :5,tls,x509verify=/etc/pki/qemu
Example 29.7: x509 Certificate and Password Authentication

You can combine the password authentication with TLS encryption and x509 certificate authentication to create a two-layer authentication model for clients. Remember to set the password in the QEMU monitor after you run the following command:

qemu-system-x86_64 [...] -vnc :5,password,tls,x509verify=/etc/pki/qemu \
-monitor stdio
Example 29.8: SASL Authentication

Simple Authentication and Security Layer (SASL) is a framework for authentication and data security in Internet protocols. It integrates several authentication mechanisms, like PAM, Kerberos, LDAP and more. SASL keeps its own user database, so the connecting user accounts do not need to exist on VM Host Server.

For security reasons, you are advised to combine SASL authentication with TLS encryption and x509 certificates:

qemu-system-x86_64 [...] -vnc :5,tls,x509,sasl -monitor stdio

30 Virtual Machine Administration Using QEMU Monitor

  • Filename: qemu_monitor.xml
  • ID: cha.qemu.monitor

When QEMU is running, a monitor console is provided for performing interaction with the user. Using the commands available in the monitor console, it is possible to inspect the running operating system, change removable media, take screenshots or audio grabs and control other aspects of the virtual machine.

Note
Note

The following sections list selected useful QEMU monitor commands and their purpose. To get the full list, enter help in the QEMU monitor command line.

30.1 Accessing Monitor Console

You can access the monitor console from QEMU window either by a keyboard shortcut—press CtrlAlt2 (to return to QEMU, press CtrlAlt1)—or alternatively by clicking View in the QEMU GUI window, then compatmonitor0. The most convenient way is to show the QEMU window tabs with View › Show Tabs. Then you can easily switch between the guest screen, monitor screen, and the output of the serial and parallel console.

To get help while using the console, use help or ?. To get help for a specific command, use help COMMAND.

30.2 Getting Information about the Guest System

To get information about the guest system, use info. If used without any option, the list of possible options is printed. Options determine which part of the system will be analyzed:

info version

Shows the version of QEMU.

info commands

Lists available QMP commands.

info network

Shows the network state.

info chardev

Shows the character devices.

info block

Information about block devices, such as hard disks, floppy drives, or CD-ROMs.

info blockstats

Read and write statistics on block devices.

info registers

Shows the CPU registers.

info cpus

Shows information about available CPUs.

info history

Shows the command line history.

info irq

Shows the interrupt statistics.

info pic

Shows the i8259 (PIC) state.

info pci

Shows the PCI information.

info tlb

Shows virtual to physical memory mappings.

info mem

Shows the active virtual memory mappings.

info jit

Shows dynamic compiler information.

info kvm

Shows the KVM information.

info numa

Shows the NUMA information.

info usb

Shows the guest USB devices.

info usbhost

Shows the host USB devices.

info profile

Shows the profiling information.

info capture

Shows the capture (audio grab) information.

info snapshots

Shows the currently saved virtual machine snapshots.

info status

Shows the current virtual machine status.

info pcmcia

Shows the guest PCMCIA status.

info mice

Shows which guest mice are receiving events.

info vnc

Shows the VNC server status.

info name

Shows the current virtual machine name.

info uuid

Shows the current virtual machine UUID.

info usernet

Shows the user network stack connection states.

info migrate

Shows the migration status.

info balloon

Shows the balloon device information.

info qtree

Shows the device tree.

info qdm

Shows the qdev device model list.

info roms

Shows the ROMs.

info migrate_cache_size

Shows the current migration xbzrle (Xor Based Zero Run Length Encoding) cache size.

info migrate_capabilities

Shows the status of the various migration capabilities, such as xbzrle compression.

info mtree

Shows the VM Guest memory hierarchy.

info trace-events

Shows available trace-events and their status.

30.3 Changing VNC Password

To change the VNC password, use the change vnc password command and enter the new password:

(qemu) change vnc password
Password: ********
(qemu)

30.4 Managing Devices

To add a new disk while the guest is running (hotplug), use the drive_add and device_add commands. First define a new drive to be added as a device to bus 0:

(qemu) drive_add 0 if=none,file=/tmp/test.img,format=raw,if=disk1
OK

You can confirm your new device by querying the block subsystem:

(qemu) info block
[...]
disk1: removable=1 locked=0 tray-open=0 file=/tmp/test.img ro=0 drv=raw \
encrypted=0 bps=0 bps_rd=0 bps_wr=0 iops=0 iops_rd=0 iops_wr=0

After the new drive is defined, it needs to be connected to a device so that the guest can see it. The typical device would be a virtio-blk-pci or scsi-disk. To get the full list of available driver values, run:

(qemu) device_add ?
name "VGA", bus PCI
name "usb-storage", bus usb-bus
[...]
name "virtio-blk-pci", bus virtio-bus

Now add the device

(qemu) device_add virtio-blk-pci,drive=disk1,id=myvirtio1

and confirm with

(qemu) info pci
[...]
Bus  0, device   4, function 0:
    SCSI controller: PCI device 1af4:1001
      IRQ 0.
      BAR0: I/O at 0xffffffffffffffff [0x003e].
      BAR1: 32 bit memory at 0xffffffffffffffff [0x00000ffe].
      id "myvirtio1"
Tip
Tip

Devices added with the device_add command can be removed from the guest with device_del. Enter help device_del on the QEMU monitor command line for more information.

To release the device or file connected to the removable media device, use the eject DEVICE command. Use the optional -f to force ejection.

To change removable media (like CD-ROMs), use the change DEVICE command. The name of the removable media can be determined using the info block command:

(qemu) info block
ide1-cd0: type=cdrom removable=1 locked=0 file=/dev/sr0 ro=1 drv=host_device
(qemu) change ide1-cd0 /path/to/image

30.5 Controlling Keyboard and Mouse

It is possible to use the monitor console to emulate keyboard and mouse input if necessary. For example, if your graphical user interface intercepts some key combinations at low level (such as CtrlAltF1 in X Window), you can still enter them using the sendkey KEYS:

sendkey ctrl-alt-f1

To list the key names used in the KEYS option, enter sendkey and press →|.

To control the mouse, the following commands can be used:

mouse_moveDXdy [DZ]

Move the active mouse pointer to the specified coordinates dx, dy with the optional scroll axis dz.

mouse_buttonVAL

Change the state of the mouse buttons (1=left, 2=middle, 4=right).

mouse_setINDEX

Set which mouse device receives events. Device index numbers can be obtained with the info mice command.

30.6 Changing Available Memory

If the virtual machine was started with the -balloon virtio option (the paravirtualized balloon device is therefore enabled), you can change the available memory dynamically. For more information about enabling the balloon device, see Section 28.1, “Basic Installation with qemu-system-ARCH.

To get information about the balloon device in the monitor console and to determine whether the device is enabled, use the info balloon command:

(qemu) info balloon

If the balloon device is enabled, use the balloon MEMORY_IN_MB command to set the requested amount of memory:

(qemu) balloon 400

30.7 Dumping Virtual Machine Memory

To save the content of the virtual machine memory to a disk or console output, use the following commands:

memsaveADDRSIZEFILENAME

Saves virtual memory dump starting at ADDR of size SIZE to file FILENAME

pmemsaveADDRSIZEFILENAME

Saves physical memory dump starting at ADDR of size SIZE to file FILENAME-

x /FMTADDR

Makes a virtual memory dump starting at address ADDR and formatted according to the FMT string. The FMT string consists of three parameters COUNTFORMATSIZE:

The COUNT parameter is the number of items to be dumped.

The FORMAT can be x (hex), d (signed decimal), u (unsigned decimal), o (octal), c (char) or i (assembly instruction).

The SIZE parameter can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86, h or w can be specified with the i format to respectively select 16 or 32-bit code instruction size.

xp /FMTADDR

Makes a physical memory dump starting at address ADDR and formatted according to the FMT string. The FMT string consists of three parameters COUNTFORMATSIZE:

The COUNT parameter is the number of the items to be dumped.

The FORMAT can be x (hex), d (signed decimal), u (unsigned decimal), o (octal), c (char) or i (asm instruction).

The SIZE parameter can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86, h or w can be specified with thei format to respectively select 16 or 32-bit code instruction size.

30.8 Managing Virtual Machine Snapshots

Managing snapshots in QEMU monitor is not officially supported by SUSE yet. The information found in this section may be helpful in specific cases.

Virtual Machine snapshots are snapshots of the complete virtual machine including the state of CPU, RAM, and the content of all writable disks. To use virtual machine snapshots, you must have at least one non-removable and writable block device using the qcow2 disk image format.

Snapshots are helpful when you need to save your virtual machine in a particular state. For example, after you have configured network services on a virtualized server and want to quickly start the virtual machine in the same state that was saved last. You can also create a snapshot after the virtual machine has been powered off to create a backup state before you try something experimental and possibly make VM Guest unstable. This section introduces the former case, while the latter is described in Section 28.2.3, “Managing Snapshots of Virtual Machines with qemu-img”.

The following commands are available for managing snapshots in QEMU monitor:

savevmNAME

Creates a new virtual machine snapshot under the tag NAME or replaces an existing snapshot.

loadvmNAME

Loads a virtual machine snapshot tagged NAME.

delvm

Deletes a virtual machine snapshot.

info snapshots

Prints information about available snapshots.

(qemu) info snapshots
Snapshot list:
ID1      TAG2                 VM SIZE3   DATE4          VM CLOCK5
1         booting                4.4M 2013-11-22 10:51:10   00:00:20.476
2         booted                 184M 2013-11-22 10:53:03   00:02:05.394
3         logged_in              273M 2013-11-22 11:00:25   00:04:34.843
4         ff_and_term_running    372M 2013-11-22 11:12:27   00:08:44.965

1

Unique identification number of the snapshot. Usually auto-incremented.

2

Unique description string of the snapshot. It is meant as a human readable version of the ID.

3

The disk space occupied by the snapshot. Note that the more memory is consumed by running applications, the bigger the snapshot is.

4

Time and date the snapshot was created.

5

The current state of the virtual machine's clock.

30.9 Suspending and Resuming Virtual Machine Execution

The following commands are available for suspending and resuming virtual machines:

stop

Suspends the execution of the virtual machine.

cont

Resumes the execution of the virtual machine.

system_reset

Resets the virtual machine. The effect is similar to the reset button on a physical machine. This may leave the file system in an unclean state.

system_powerdown

Sends an ACPI shutdown request to the machine. The effect is similar to the power button on a physical machine.

q or quit

Terminates QEMU immediately.

30.10 Live Migration

The live migration process allows to transmit any virtual machine from one host system to another host system without any interruption in availability. It is possible to change hosts permanently or only during maintenance.

The requirements for live migration:

  • All requirements from Section 10.7.1, “Migration Requirements” are applicable.

  • Live migration is only possible between VM Host Servers with the same CPU features.

  • AHCI interface, VirtFS feature, and the -mem-path command line option are not compatible with migration.

  • The guest on the source and destination hosts must be started in the same way.

  • -snapshot qemu command line option should not be used for migration (and this qemu command line option is not supported).

Important
Important: Support Status

The postcopy mode is not yet supported in SUSE Linux Enterprise Server. It is released as a technology preview only. For more information about postcopy, see http://wiki.qemu.org/Features/PostCopyLiveMigration.

More recommendations can be found at the following Web site: http://www.linux-kvm.org/page/Migration

The live migration process has the following steps:

  1. The virtual machine instance is running on the source host.

  2. The virtual machine is started on the destination host in the frozen listening mode. The parameters used are the same as on the source host plus the -incoming tcp:IP:PORT parameter, where IP specifies the IP address and PORT specifies the port for listening to the incoming migration. If 0 is set as IP address, the virtual machine listens on all interfaces.

  3. On the source host, switch to the monitor console and use the migrate -d tcp: DESTINATION_IP:PORT command to initiate the migration.

  4. To determine the state of the migration, use the info migrate command in the monitor console on the source host.

  5. To cancel the migration, use the migrate_cancel command in the monitor console on the source host.

  6. To set the maximum tolerable downtime for migration in seconds, use the migrate_set_downtime NUMBER_OF_SECONDS command.

  7. To set the maximum speed for migration in bytes per second, use the migrate_set_speed BYTES_PER_SECOND command.

30.11 QMP - QEMU Machine Protocol

QMP is a JSON-based protocol that allows applications—such as libvirt—to communicate with a running QEMU instance. There are several ways you can access the QEMU monitor using QMP commands.

30.11.1 Access QMP via Standard Input/Output

The most flexible way to use QMP is by specifying the -mon option. The following example creates a QMP instance using standard input/output. Note that in the following examples, -> marks lines with commands sent from client to the running QEMU instance, while <- marks lines with the output returned from QEMU.

# qemu-system-x86_64 [...] \
-chardev stdio,id=mon0 \
-mon chardev=mon0,mode=control,pretty=on

<- {
    "QMP": {
        "version": {
            "qemu": {
                "micro": 0,
                "minor": 0,
                "major": 2
            },
            "package": ""
        },
        "capabilities": [
        ]
    }
}

When a new QMP connection is established, QMP sends its greeting message and enters capabilities negotiation mode. In this mode, only the qmp_capabilities command works. To exit capabilities negotiation mode and enter command mode, the qmp_capabilities command must be issued first:

-> { "execute": "qmp_capabilities" }
<- {
    "return": {
    }
}

Note that "return": {} is a QMP's success response.

QMP's commands can have arguments. For example to eject a CD-ROM drive, enter the following:

->{ "execute": "eject", "arguments": { "device": "ide1-cd0" } }
<- {
    "timestamp": {
        "seconds": 1410353381,
        "microseconds": 763480
    },
    "event": "DEVICE_TRAY_MOVED",
    "data": {
        "device": "ide1-cd0",
        "tray-open": true
    }
}
{
    "return": {
    }
}

30.11.2 Access QMP via Telnet

Instead of the standard input/output, you can connect the QMP interface to a network socket and communicate with it via a specified port:

# qemu-system-x86_64 [...] \
-chardev socket,id=mon0,host=localhost,port=4444,server,nowait \
-mon chardev=mon0,mode=control,pretty=on

And then run telnet to connect to port 4444:

# telnet localhost 4444
Trying ::1...
Connected to localhost.
Escape character is '^]'.
<- {
    "QMP": {
        "version": {
            "qemu": {
                "micro": 0,
                "minor": 0,
                "major": 2
            },
            "package": ""
        },
        "capabilities": [
        ]
    }
}

You can create several monitor interfaces at the same time. The following example creates one HMP instance—human monitor which understands 'normal' QEMU monitor's commands—on the standard input/output, and one QMP instance on localhost port 4444:

# qemu-system-x86_64 [...] \
-chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
-chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
  -mon chardev=mon1,mode=control,pretty=on

30.11.3 Access QMP via Unix Socket

Invoke QEMU using the -qmp option, and create a unix socket:

# qemu-system-x86_64 [...] \
-qmp unix:/tmp/qmp-sock,server --monitor stdio

QEMU waiting for connection on: unix:./qmp-sock,server

To communicate with the QEMU instance via the /tmp/qmp-sock socket, use nc (see man 1 nc for more information) from another terminal on the same host:

# nc -U /tmp/qmp-sock
<- {"QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 2} [...]

30.11.4 Access QMP via libvirt's virsh Command

If you run your virtual machines under libvirt (see Part II, “Managing Virtual Machines with libvirt), you can communicate with its running guests by running the virsh qemu-monitor-command:

# virsh qemu-monitor-command vm_guest1 \
--pretty '{"execute":"query-kvm"}'
<- {
    "return": {
        "enabled": true,
        "present": true
    },
    "id": "libvirt-8"
}

In the above example, we ran the simple command query-kvm which checks if the host is capable of running KVM and if KVM is enabled.

Tip
Tip: Generating Human-Readable Output

To use the standard human-readable output format of QEMU instead of the JSON format, use the --hmp option:

# virsh qemu-monitor-command vm_guest1 --hmp "query-kvm"

Part VI Managing Virtual Machines with LXC

31 Linux Containers

32 Migration from LXC to libvirt-lxc

Since SUSE Linux Enterprise Server 12, LXC is integrated into libvirt library. This decision has several advantages over using LXC as a separate solution—such as a unified approach with other virtualization solutions or independence on the kernel used. This chapter describes steps needed to migrate …

31 Linux Containers

  • Filename: lxc.xml
  • ID: cha.lxc

31.1 Setting Up LXC Distribution Containers

A container is a kind of virtual machine that can be started, stopped, frozen, or cloned (to name but a few tasks). To set up an LXC container, you first need to create a root file system containing the guest distribution:

Procedure 31.1: Creating a Root File System

There is currently no GUI to create a root file system. You will thus need to open a terminal and use virt-create-rootfs as root to populate the new root file system. In the following steps, the new root file system will be created in /path/to/rootfs.

Important
Important: Registration Code Needed

virt-create-rootfs needs a registration code to set up a SUSE Linux Enterprise Server root file system.

  1. Run the virt-create-rootfs command:

    virt-create-rootfs --root /PATH/TO/ROOTFS --distro SLES-12.0 -c REGISTRATION_CODE
  2. Change the root path to the root file system with the chroot command:

    chroot /path/to/rootfs
  3. Change the password for user root with passwd.

  4. Create an operator user without root privileges:

    useradd -m operator
  5. Change the operator's password:

    passwd operator
  6. Leave the chroot environment with exit.

Procedure 31.2: Defining the Container
  1. Start Virtual Machine Manager.

  2. (Optional) If not already present, add a local LXC connection by clicking File › Add Connection.

    Select LXC (Linux Containers) as the hypervisor and click Connect.

  3. Select the localhost (LXC) connection and click File New Virtual Machine menu.

  4. Activate Operating system container and click Forward.

  5. Type the path to the root file system from Procedure 31.1, “Creating a Root File System” and click the Forward button.

  6. Choose the maximum amount of memory and CPUs to allocate to the container. Then click the Forward button.

  7. Type in a name for the container. This name will be used for all virsh commands on the container.

    Click Advanced options. Select the network to connect the container to and click the Finish button: the container will then be created and started. A console will also be automatically opened.

Procedure 31.3: Configuring IP Addresses for Network Interfaces

Network devices and hostdev devices with network capabilities can be provided with one or more IP addresses to set on the network device in the guest. However, some hypervisors or network device types will simply ignore them or only use the first one.

  1. Edit the container XML configuration using virsh:

    virsh -c lxc:/// edit MYCONTAINER
  2. The following example shows how to set one ore multiple IP addresses:

    [...]
    <devices>
     <interface type='network'>
      <source network='default'/>
      <target dev='vnet0'/>
      <ip address='192.168.122.5' prefix='24'/>
      <ip address='192.168.122.5' prefix='24' peer1='10.0.0.10'/>
       <route family2='ipv4' address3='192.168.122.0' prefix4='24'
              gateway5='192.168.122.1'/>
       <route family2='ipv4' address3='192.168.122.8' gateway5='192.168.122.1'/>
     </interface>
     [...]
     <hostdev mode='capabilities' type='net'>
      <source>
       <interface>eth0</interface>
      </source>
      <ip address='192.168.122.6' prefix='24'/>
      <route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/>
      <route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/>
     </hostdev>
    </devices>
    [...]

    1

    Optional attribute. Holds the IP address of the other end of a point-to-point network device.

    2

    Can be set to either ipv4 or ipv6.

    3

    Contains the IP address.

    4

    Optional parameter (will be automatically set if not specified). Defines the number of 1 bits in the netmask. For IPv4, the default prefix is determined according to the network class (A, B, or C). For IPv6, the default prefix is 64.

    5

    If you do not specify a default gateway in the XML file, none will be set.

  3. You can also add route elements to define IP routes to add in the guest. This is used by the LXC driver.

    [...]
    <devices>
     <interface type1='ethernet'>
      <source/>2
       <ip address3='192.168.123.1' prefix='24'/>
       <ip address4='10.0.0.10' prefix='24' peer='192.168.122.5'/>
       <route5 family='ipv4' address='192.168.42.0' prefix='24'
                gateway='192.168.123.4'/>
      <source/>
      [...]
     </interface>
     [...]
    </devices>
    [...]

    1

    Network devices of type ethernet can optionally be provided with one or multiple IP addresses (3, 4) and with one or multiple routes (5) to set on the host side of the network device.

    These are configured as subelements of the source element (2) of the interface. They have the same attributes as the similarly named elements used to configure the guest side of the interface (see the step above).

    3

    First IP address for the network device of type ethernet.

    4

    Second IP address for the network device of type ethernet.

    5

    Route to set on the host side of the network device.

    Find further details about the attributes of this element at http://libvirt.org/formatnetwork.html#elementsStaticroute.

  4. Save the changes and exit the editor.

Note
Note: Container Network

To configure the container network, edit the /etc/sysconfig/network/ifcfg-* files.

31.2 Setting Up LXC Application Containers

Libvirt also allows to run single applications instead of full blown Linux distributions in containers. In this example, bash will be started in its own container.

Procedure 31.4: Defining an Application Container Using YaST
  1. Start Virtual Machine Manager.

  2. (Optional) If not already present, add a local LXC connection by clicking File › Add Connection.

    Select LXC (Linux Containers) as the hypervisor and click Connect.

  3. Select the localhost (LXC) connection and click File New Virtual Machine menu.

  4. Activate Application container and click Forward.

    Set the path to the application to be launched. As an example, the field is filled with /bin/sh, which is fine to create a first container. Click Forward.

  5. Choose the maximum amount of memory and CPUs to allocate to the container. Click Forward.

  6. Type in a name for the container. This name will be used for all virsh commands on the container.

    Click Advanced options. Select the network to connect the container to and click Finish. The container will be created and started. A console will be opened automatically.

    Note that the container will be destroyed after the application has finished running.

31.3 Securing a Container Using AppArmor

By default, containers are not secured using AppArmor or SELinux. There is no graphical user interface to change the security model for a libvirt domain, but virsh will help.

  1. Edit the container XML configuration using virsh:

    virsh -c lxc:/// edit MYCONTAINER
  2. Add the following to the XML configuration, save it and exit the editor.

    <domain>
        ...
        <seclabel type="dynamic" model="apparmor"/>
        ...
    </domain>
  3. With this configuration, an AppArmor profile for the container will be created in the /etc/apparmor.d/libvirt directory. The default profile only allows the minimum applications to run in the container. This can be changed by modifying the libvirt-CONTAINER-uuid file: this file is not overwritten by libvirt.

31.4 Differences Between the libvirt LXC Driver and LXC

SUSE Linux Enterprise Server 11 SP3 was shipping LXC, while SUSE Linux Enterprise Server 12 comes with the libvirt LXC driver, sometimes named libvirt-lxc to avoid confusion. The containers are not managed or configured in the same way in these tools. Here is a non-exhaustive list of differences.

The main difference is that domain configuration in libvirt is an XML file, while LXC configuration is a properties file. Most of the LXC properties can be mapped to the domain XML. The properties that cannot be migrated are:

  • lxc.network.script.up: this script can be implemented using the /etc/libvirt/hooks/network libvirt hook, though the script will need to be adapted.

  • lxc.network.ipv*: libvirt cannot set the container network configuration from the domain configuration.

  • lxc.network.name: libvirt cannot set the container network card name.

  • lxc.devttydir: libvirt does not allow changing the location of the console devices.

  • lxc.console: there is currently no way to log the output of the console into a file on the host for libvirt LXC containers.

  • lxc.pivotdir: libvirt does not allow to fine-tune the directory used for the pivot_root. /.olroot is used.

  • lxc.rootfs.mount: libvirt does not allow to fine-tune this.

LXC VLAN networks automatically create the VLAN interface on the host and then move it into the guest namespace. libvirt-lxc configuration can mention a VLAN tag ID only for Open vSwitch tap devices or PCI pass-through of SR-IOV VF. The conversion tool actually needs the user to manually create the VLAN interface on the host side.

LXC rootfs can also be an image file, but LXC brute-forces the mount to try to detect the proper file system format. libvirt-lxc can mount image files of several formats, but the 'auto' value for the format parameter is explicitly not supported. This means that the generated configuration will need to be tweaked by the user to get a proper match in that case.

LXC can support any cgroup configuration, even future ones, while libvirt domain configuration, needs to map each of them.

LXC can mount block devices in the rootfs, but it cannot mount raw partition files: the file needs to be manually attached to a loop device. On the other hand libvirt-lxc can mount block devices, but also partition files of any format.

31.5 Sharing Namespaces Across Containers

Like Docker, libvirt allows you to inherit the namespace from containers or processes to share the network namespace. The following example shows how to share required namespaces.

<domain type='lxc' xmlns:lxc='http://libvirt.org/schemas/domain/lxc/1.0'>
 [...]
 <lxc:namespace>
  <lxc:sharenet type='netns' value='red'/>
  <lxc:shareuts type='name' value='CONTAINER_1'/>
  <lxc:shareipc type='pid' value='12345'/>
 </lxc:namespace>
 </domain>

The netns option is specific to sharenet. Use it to use an existing network namespace (instead of creating a new network namespace for the container). In this case, the privnet option will be ignored.

31.6 For More Information

LXC Container Driver

http://libvirt.org/drvlxc.html

32 Migration from LXC to libvirt-lxc

  • Filename: lxc2libvirt.xml
  • ID: cha.lxc2libvirt

Since SUSE Linux Enterprise Server 12, LXC is integrated into libvirt library. This decision has several advantages over using LXC as a separate solution—such as a unified approach with other virtualization solutions or independence on the kernel used. This chapter describes steps needed to migrate an existing LXC environment for use with the libvirt library.

32.1 Host Migration

The migration itself has two phases. You first need to migrate the host, then the LXC containers. After that, you can run the original containers as VM Guests in the libvirt environment.

Procedure 32.1: Host Migration
  1. Upgrade the host to SUSE Linux Enterprise Server 12 12 using the official DVD media.

  2. After the upgrade, install the libvirt-daemon-lxc and libvirt-daemon-config-network packages.

  3. Create a libvirt XML configuration lxc_container.xml from the existing container lxc_container:

    # virt-lxc-convert /etc/lxc/lxc_container/config > lxc_container.xml
  4. Check if the network configuration on the host is the same as in the container configuration file, and fix it if needed.

  5. Check the lxc_container.xml file for any weird or missing configuration. Note that some LXC configuration options cannot be mapped to libvirt configuration. Although the conversion should usually be fine, check Section 31.4, “Differences Between the libvirt LXC Driver and LXC” for more details.

  6. Define the container in libvirt based on the created XML definition:

    # virsh -c lxc:/// define lxc_container.xml

32.2 Container Migration

After the host is migrated, the LXC container in libvirt will not boot. It needs to be migrated to SUSE Linux Enterprise Server 12 as well to get everything working.

Procedure 32.2: Container Migration
  1. The baseproduct file is missing (and zypper keeps complaining about it). Create the relevant symbolic link:

    # ROOTFS=/var/lib/lxc/lxc_container/rootfs
    # ln -s $ROOTFS/etc/products.d/SUSE_SLES.prod $ROOTFS/etc/products.d/baseproduct
  2. Add the DVD repository. Note that you need to replace the DVD device with the one attached to your container:

    # zypper --root $ROOTFS ar \
    cd:///?devices=/dev/dvd SLES12-12
  3. Disable or remove previous repositories:

    # zypper --root $ROOTFS lr
      | Alias                       | Name                         | Enabled | Refresh
    --+-----------------------------+------------------------------+---------+--------
    1 | SLES12-12                   | SLES12-12                    | Yes     | No
    2 | SUSE-[...]-Server-11-SP3 38 | SUSE-[...]-Server-11-SP3 138 | Yes     | No
    
    # zypper --root $ROOTFS rr 2
  4. Upgrade the container:

    # zypper --root $ROOTFS dup
  5. Install the Minimal pattern to make sure everything required is installed:

    # zypper --root $ROOTFS in -t pattern Minimal

32.3 Starting the Container

After the host and container migration is complete, the container can be started:

# virsh -c lxc:/// start lxc_container

If you need to get a console to view the logging messages produced by the container, run:

# virsh -c lxc:/// console lxc_container

Glossary

  • Filename: vt_glossary.xml
  • ID: book.virt

General

Virtual Machine Manager

A software program that provides a graphical user interface for creating and managing virtual machines.

Virtualized

A guest operating system or application running on a virtual machine.

Virtual Machine

A virtualized PC environment (VM) capable of hosting a guest operating system and associated applications. Could be also called a VM Guest.

VHS

Virtualization Host Server

The physical computer running a SUSE virtualization platform software. The virtualization environment consists of the hypervisor, the host environment, virtual machines, and associated tools, commands, and configuration files. Other commonly used terms include host, Host Computer, Host Machine (HM), Virtual Server (VS), Virtual Machine Host (VMH), and VM Host Server (VHS).

Xen

See Chapter 2, Introduction to Xen Virtualization

KVM

See Chapter 3, Introduction to KVM Virtualization

xl

A set of commands for Xen that lets administrators manage virtual machines from a command prompt on the host computer. It replaced the deprecated xm tool stack.

hardware-assisted

Intel* and AMD* provide virtualization hardware-assisted technology. This reduces the frequency of VM IN/OUT (fewer VM traps), because software is a major source of overhead, and increases the efficiency (the execution is done by the hardware). Moreover, this reduces the memory footprint, provides better resource control, and allows secure assignment of specific I/O devices.

Dom0

The term is used in Xen environments, and refers to a virtual machine. The host operating system is actually a virtual machine running in a privileged domain and can be called Dom0. All other virtual machines on the host run in unprivileged domains and can be called domain U's.

Create Virtual Machine Wizard

A software program available in YaST and Virtual Machine Manager that provides a graphical interface to guide you through the steps to create virtual machines. It can also be run in text mode by entering virt-install at a command prompt in the host environment.

Host Environment

The desktop or command line environment that allows interaction with the host computer's environment. It provides a command line environment and can also include a graphical desktop, such as GNOME or IceWM. The host environment runs as a special type of virtual machine that has privileges to control and manage other virtual machines. Other commonly used terms include Dom0, privileged domain, and host operating system.

Hypervisor

The software that coordinates the low-level interaction between virtual machines and the underlying physical computer hardware.

Paravirtualized Frame Buffer

The video output device that drives a video display from a memory buffer containing a complete frame of data for virtual machine displays running in paravirtual mode.

VirtFS

VirtFS is a new paravirtualized file system interface designed for improving pass-through technologies in the KVM environment. It is based on the VirtIO framework.

CPU

CPU capping

Virtual CPU capping allows you to set vCPU capacity to 1–100 percent of the physical CPU capacity.

CPU over-commitment

Virtual CPU over-commitment is the ability to assign more virtual CPUs to VMs than the actual number of physical CPUs present in the physical system. This procedure does not increase the overall performance of the system, but might be useful for testing purposes.

CPU hotplugging

CPU hotplugging is used to describe the functions of replacing/adding/removing a CPU without shutting down the system.

CPU pinning

Processor affinity, or CPU pinning enables the binding and unbinding of a process or a thread to a central processing unit (CPU) or a range of CPUs.

Network

Bridged Networking

A type of network connection that lets a virtual machine be identified on an external network as a unique identity that is separate from and unrelated to its host computer.

Empty Bridge

A type of network bridge that has no physical network device or virtual network device provided by the host. This lets virtual machines communicate with other virtual machines on the same host but not with the host or on an external network.

External Network

The network outside a host's internal network environment.

Internal Network

A type of network configuration that restricts virtual machines to their host environment.

Local Bridge

A type of network bridge that has a virtual network device but no physical network device provided by the host. This lets virtual machines communicate with the host and other virtual machines on the host. Virtual machines can communicate on an external network through the host.

Network Address Translation (NAT)

A type of network connection that lets a virtual machine use the IP address and MAC address of the host.

No Host Bridge

A type of network bridge that has a physical network device but no virtual network device provided by the host. This lets virtual machines communicate on an external network but not with the host. This lets you separate virtual machine network communications from the host environment.

Traditional Bridge

A type of network bridge that has both a physical network device and a virtual network device provided by the host.

Storage

AHCI

The Advanced Host Controller Interface (AHCI) is a technical standard defined by Intel* that specifies the operation of Serial ATA (SATA) host bus adapters in a non-implementation-specific manner.

Block Device

Data storage devices, such as CD-ROM drives or disk drives, that move data in the form of blocks. Partitions and volumes are also considered block devices.

File-Backed Virtual Disk

A virtual disk based on a file, also called a disk image file.

Raw Disk

A method of accessing data on a disk at the individual byte level instead of through its file system.

Sparse image file

A disk image file that does not reserve its entire amount of disk space but expands as data is written to it.

xvda

The drive designation given to the first virtual disk on a paravirtual machine.

Linux Containers

cgroups

Kernel Control Groups (commonly called cgroups) are a kernel feature that allows aggregating or partitioning tasks (processes) and all their children into hierarchical organized groups to isolate resources.

See also Chapter 9, Kernel Control Groups.

chroot

A change root (chroot, or change root jail) is a section in the file system that is isolated from the rest of the file system. For this purpose, the chroot or pivot_root command is used to change the root of the file system. A program that is executed in such a chroot jail cannot access files outside the designated directory tree.

container

Can be seen as a kind of virtual machine on the host server that can run any Linux system, for example openSUSE, SUSE Linux Enterprise Desktop, or SUSE Linux Enterprise Server. The main difference with a normal virtual machine is that the container shares its kernel with the host it runs on.

Kernel namespaces

A kernel feature to isolate some resources like network, users, and others for a group of processes.

Acronyms

ACPI

Advanced Configuration and Power Interface (ACPI) specification provides an open standard for device configuration and power management by the operating system.

AER

Advanced Error Reporting

AER is a capability provided by the PCI Express specification which allows for reporting of PCI errors and recovery from some of them.

APIC

Advanced Programmable Interrupt Controller (APIC) is a family of interrupt controllers.

BDF

Bus:Device:Function

Notation used to succinctly describe PCI and PCIe devices.

CG

Control Groups

Feature to limit, account and isolate resource usage (CPU, memory, disk I/O, etc.).

EDF

Earliest Deadline First

This scheduler provides weighted CPU sharing in an intuitive way and uses real-time algorithms to ensure time guarantees.

EPT

Extended Page Tables

Performance in a virtualized environment is close to that in a native environment. Virtualization does create some overheads, however. These come from the virtualization of the CPU, the MMU, and the I/O devices. In some recent x86 processors AMD and Intel have begun to provide hardware extensions to help bridge this performance gap. In 2006, both vendors introduced their first generation hardware support for x86 virtualization with AMD-Virtualization (AMD-V) and Intel® VT-x technologies. Recently Intel introduced its second generation of hardware support that incorporates MMU-virtualization, called Extended Page Tables (EPT). EPT-enabled systems can improve performance compared to using shadow paging for MMU virtualization. EPT increases memory access latencies for a few workloads. This cost can be reduced by effectively using large pages in the guest and the hypervisor.

FLASK

Flux Advanced Security Kernel

Xen implements a type of mandatory access control via a security architecture called FLASK using a module of the same name.

HAP

High Assurance Platform

HAP combines hardware and software technologies to improve workstation and network security.

HVM

Hardware Virtual Machine (commonly called like this by Xen).

IOMMU

Input/Output Memory Management Unit

IOMMU (AMD* technology) is a memory management unit (MMU) that connects a direct memory access-capable (DMA-capable) I/O bus to the main memory.

KSM

Kernel Same Page Merging

KSM allows for automatic sharing of identical memory pages between guests to save host memory. KVM is optimized to use KSM if enabled on the VM Host Server.

MMU

Memory Management Unit

is a computer hardware component responsible for handling accesses to memory requested by the CPU. Its functions include translation of virtual addresses to physical addresses (that is, virtual memory management), memory protection, cache control, bus arbitration and in simpler computer architectures (especially 8-bit systems) bank switching.

PAE

Physical Address Extension

32-bit x86 operating systems use Physical Address Extension (PAE) mode to enable addressing of more than 4 GB of physical memory. In PAE mode, page table entries (PTEs) are 64 bits in size.

PCID

Process-context identifiers

These are a facility by which a logical processor may cache information for multiple linear-address spaces so that the processor may retain cached information when software switches to a different linear address space. INVPCID instruction is used for fine-grained TLB flush, which is benefit for kernel.

PCIe

Peripheral Component Interconnect Express

PCIe was designed to replace older PCI, PCI-X and AGP bus standards. PCIe has numerous improvements including a higher maximum system bus throughput, a lower I/O pin count and smaller physical footprint. Moreover it also has a more detailed error detection and reporting mechanism (AER), and a native hotplug functionality. It is also backward compatible with PCI.

PSE and PSE36

Page Size Extended

PSE refers to a feature of x86 processors that allows for pages larger than the traditional 4 KiB size. PSE-36 capability offers 4 more bits, in addition to the normal 10 bits, which are used inside a page directory entry pointing to a large page. This allows a large page to be located in 36-bit address space.

PT

Page Table

A page table is the data structure used by a virtual memory system in a computer operating system to store the mapping between virtual addresses and physical addresses. Virtual addresses are those unique to the accessing process. Physical addresses are those unique to the hardware (RAM).

QXL

QXL is a cirrus VGA framebuffer (8M) driver for virtualized environment.

RVI or NPT

Rapid Virtualization Indexing, Nested Page Tables

An AMD second generation hardware-assisted virtualization technology for the processor memory management unit (MMU).

SATA

Serial ATA

SATA is a computer bus interface that connects host bus adapters to mass storage devices such as hard disks and optical drives.

Seccomp2-based sandboxing

Sandboxed environment where only predetermined system calls are permitted for added protection against malicious behavior.

SMEP

Supervisor Mode Execution Protection

This prevents the execution of user-mode pages by the Xen hypervisor, making many application-to-hypervisor exploits much harder.

SPICE

Simple Protocol for Independent Computing Environments

SXP

An SXP file is a Xen Configuration File.

TCG

Tiny Code Generator

Instructions are emulated rather than executed by the CPU.

THP

Transparent Huge Pages

This allows CPUs to address memory using pages larger than the default 4 KB. This helps reduce memory consumption and CPU cache usage. KVM is optimized to use THP (via madvise and opportunistic methods) if enabled on the VM Host Server.

TLB

Translation Lookaside Buffer

TLB is a cache that memory management hardware uses to improve virtual address translation speed. All current desktop, notebook, and server processors use a TLB to map virtual and physical address spaces, and it is nearly always present in any hardware that uses virtual memory.

VCPU

A scheduling entity, containing each state for virtualized CPU.

VDI

Virtual Desktop Infrastructure

VFIO

Since kernel v3.6; a new method of accessing PCI devices from user space called VFIO.

VHS

Virtualization Host Server

VMCS

Virtual Machine Control Structure

VMX non-root operation and VMX transitions are controlled by a data structure called a virtual-machine control structure (VMCS). Access to the VMCS is managed through a component of processor state called the VMCS pointer (one per logical processor). The value of the VMCS pointer is the 64-bit address of the VMCS. The VMCS pointer is read and written using the instructions VMPTRST and VMPTRLD. The VMM configures a VMCS using the VMREAD, VMWRITE, and VMCLEAR instructions. A VMM could use a different VMCS for each virtual machine that it supports. For a virtual machine with multiple logical processors (virtual processors), the VMM could use a different VMCS for each virtual processor.

VMDq

Virtual Machine Device Queue

Multi-queue network adapters exist which support multiple VMs at the hardware level, having separate packet queues associated to the different hosted VMs (by means of the IP addresses of the VMs).

VMM

Virtual Machine Monitor (Hypervisor)

When the processor encounters an instruction or event of interest to the Hypervisor (VMM), it exits from guest mode back to the VMM. The VMM emulates the instruction or other event, at a fraction of native speed, and then returns to guest mode. The transitions from guest mode to the VMM and back again are high-latency operations, during which guest execution is completely stalled.

VM root

VMM will run in VMX root operation and guest software will run in VMX non-root operation. Transitions between VMX root operation and VMX non-root operation are called VMX transitions.

VMX

Virtual Machine eXtensions

VPID

New support for software control of TLB (VPID improves TLB performance with small VMM development effort).

VT-d

Virtualization Technology for Directed I/O

Like IOMMU for Intel*.

vTPM

Component to establish end-to-end integrity for guests via Trusted Computing.

A Virtual Machine Drivers

  • Filename: vmdp_drivers.xml
  • ID: app.vmdp.driver

Virtualization allows the consolidation of workloads on newer, more powerful, energy-efficient hardware. Paravirtualized operating systems such as SUSE® Linux Enterprise Server and other Linux distributions are aware of the underlying virtualization platform, and can therefore interact efficiently with it. Unmodified operating systems such as Microsoft Windows* are unaware of the virtualization platform and expect to interact directly with the hardware. Because this is not possible when consolidating servers, the hardware must be emulated for the operating system. Emulation can be slow, but it is especially troubling for high-throughput disk and network subsystems. Most performance loss occurs in this area.

The SUSE Linux Enterprise Virtual Machine Driver Pack (VMDP) contains 32-bit and 64-bit paravirtualized network, bus and block drivers for several Microsoft Windows operating systems. These drivers bring many of the performance advantages of paravirtualized operating systems to unmodified operating systems: Only the paravirtualized device driver (not the rest of the operating system) is aware of the virtualization platform. For example, a paravirtualized disk device driver appears as a normal, physical disk to the operating system. However, the device driver interacts directly with the virtualization platform (with no emulation). This helps to efficiently deliver disk access, allowing the disk and network subsystems to operate at near native speeds in a virtualized environment, without requiring changes to existing operating systems.

The SUSE® Linux Enterprise Virtual Machine Driver Pack is available as an add-on product for SUSE Linux Enterprise Server. For detailed information refer to http://www.suse.com/products/vmdriverpack/.

Refer to the Official VMDP Installation Guide at https://www.suse.com/documentation/sle-vmdp-22/ for more information.

B Appendix

  • Filename: kvm_appendix.xml
  • ID: app.kvm

B.1 Installing Paravirtualized Drivers

B.1.1 Installing virtio Drivers for Microsoft Windows*

SUSE has developed virtio-based drivers for Windows, which are available in the Virtual Machine Driver Pack (VMDP). See http://www.suse.com/products/vmdriverpack/ for more information on the VMDP. Installation instructions are now available in a dedicated official documentation.

B.2 Generating x509 Client/Server Certificates

To be able to create x509 client and server certificates you need to issue them by a Certificate Authority (CA). It is recommended to set up an independent CA that only issues certificates for libvirt.

  1. Set up a CA as described in Section 17.2.1, “Creating a Root CA”.

  2. Create a server and a client certificate as described in Section 17.2.4, “Creating or Revoking User Certificates”. The Common Name (CN) for the server certificate must be the fully qualified host name, while the Common Name for the client certificate can be freely chosen. For all other fields stick with the defaults suggested by YaST.

    Export the client and server certificates to a temporary location (for example, /tmp/x509/) by performing the following steps:

    1. Select the certificate on the certificates tab.

    2. Choose Export › Export to File › Certificate and the Key Unencrypted in PEM Format, provide the Certificate Password and the full path and the file name under File Name, for example, /tmp/x509/server.pem or /tmp/x509/client.pem.

    3. Open a terminal and change to the directory where you have saved the certificate and issue the following commands to split it into certificate and key (this example splits the server key):

      csplit -z -f s_ server.pem '/-----BEGIN/' '{1}'
             mv s_00 servercert.pem
             mv s_01 serverkey.pem
    4. Repeat the procedure for each client and server certificate you want to export.

  3. Finally export the CA certificate by performing the following steps:

    1. Switch to the Description tab.

    2. Choose Advanced › Export to File › Only the Certificate in PEM Format and enter the full path and the file name under File Name, for example, /tmp/x509/cacert.pem.

C XM, XL Toolstacks and Libvirt framework

  • Filename: xen_xmtoxl.xml
  • ID: cha.xmtoxl

C.1 Xen Toolstacks

Since the early Xen 2.x releases, xend has been the de facto toolstack for managing Xen installations. In Xen 4.1, a new toolstack called libxenlight (also known as libxl) was introduced with technology preview status. libxl is a small, low-level library written in C. It has been designed to provide a simple API for all client toolstacks (XAPI, libvirt, xl). In Xen 4.2, libxl was promoted to officially supported status and xend was marked deprecated. xend has been included in the Xen 4.3 and 4.4 series to give users ample time to convert their tooling to libxl. It has been removed from the upstream Xen project and will no longer be provided starting with the Xen 4.5 series and SUSE Linux Enterprise Server 12 SP1.

Although SLES 11 SP3 contains Xen 4.2, SUSE retained the xend toolstack since making such an invasive change in a service pack would be too disruptive for SUSE Linux Enterprise customers. However, SLES 12 provides a suitable opportunity to move to the new libxl toolstack and remove the deprecated, unmaintained xend stack. Starting with SUSE Linux Enterprise Server 12 SP1, xend is no longer supported.

One of the major differences between xend and libxl is that the former is stateful, while the latter is stateless. With xend, all client applications such as xm and libvirt see the same system state. xend is responsible for maintaining state for the entire Xen host. In libxl, client applications such as xl or libvirt must maintain state. Thus domains created with xl or not visible or known to other libxl applications such as libvirt. Generally, it is discouraged to mix and match libxl applications and is preferred that a single libxl application be used to manage a Xen host. In SUSE Linux Enterprise 12 , we recommend to use libvirt to manage Xen hosts. This allows management of the Xen system through libvirt applications such as virt-manager, virt-install, virt-viewer, libguestfs, etc. If xl is used to manage the Xen host, any virtual machines under its management will not be accessible to libvirt. Hence, they are not accessible to any of the libvirt applications.

C.1.1 Upgrading from xend/xm to xl/libxl

The xl application, along with its configuration format (see man xl.cfg), was designed to be backward-compatible with the xm application and its configuration format (see man xm.cfg). Existing xm configuration should be usable with xl. Since libxl is stateless, and xl does not support the notion of managed domains, SUSE recommends using libvirt to manage SLES 12 Xen hosts. SUSE has provided a tool called xen2libvirt, which provides a simple mechanism to import domains previously managed by xend into libvirt. See Section C.2, “Import Xen Domain Configuration into libvirt for more information on xen2libvirt.

C.1.2 XL design

The basic structure of every xl command is:

xl subcommand OPTIONS DOMAIN

DOMAIN is the numeric domain id, or the domain name (which will be internally translated to domain id), and OPTIONS are subcommand specific options.

Although xl/libxl was designed to be backward-compatible with xm/xend, there are a few differences that should be noted:

  • Managed or persistent domains. libvirt now provides this functionality.

  • xl/libxl does not support Python code in the domain configuration files.

  • xl/libxl does not support creating domains from SXP format configuration files (xm create -F).

  • xl/libxl does not support sharing storage across DomU's via w! in domain configuration files.

xl/libxl is relatively new and under heavy development, hence a few features are still missing with regard to the xm/xend toolstack:

  • SCSI LUN/Host pass-through (PVSCSI)

  • USB pass-through (PVUSB)

  • Direct Kernel Boot for fully virtualized Linux guests for Xen

C.1.3 Checklist before Upgrade

Before upgrading a SLES 11 SP3 Xen host to SLES 12:

  • You must remove any Python code from your xm domain configuration files.

  • It is recommended to capture the libvirt domain XML from all existing virtual machines using virsh dumpxml DOMAIN_NAME DOMAIN_NAME.xml.

  • It is recommended to do a backup of /etc/xen/xend-config.sxp and /boot/grub/menu.lst files to keep references of previous parameters used for Xen.

Note
Note

Currently, live migrating virtual machines running on a SLES 11 SP3 Xen host to a SLES 12 Xen host is not supported. The xend and libxl toolstacks are not runtime-compatible. Virtual machine downtime will be required to move the virtual machines from SLES 11 SP3 to a SLES 12 host.

C.2 Import Xen Domain Configuration into libvirt

  • Filename: xm_vs_xl_xen2libvirt.xml
  • ID: xen.xen2libvirt

xen2libvirt is a command line tool to import legacy Xen domain configuration into the libvirt virtualization library (see The Virtualization book for more information on libvirt). xen2libvirt provides an easy way to import domains managed by the deprecated xm/xend tool stack into the new libvirt/libxl tool stack. Several domains can be imported at once using its --recursive mode

xen2libvirt is included in the xen-tools package. If needed, install it with

zypper install xen-tools

xen2libvirt general syntax is

xen2libvirt <options> /path/to/domain/config

where options can be:

-h, --help

Prints short information about xen2libvirt usage.

-c, --convert-only

Converts the domain configuration to the libvirt XML format, but does not do the import to libvirt.

-r, --recursive

Converts and/or imports all domains configuration recursively, starting at the specified path.

-f, --format

Specifies the format of the source domain configuration. Can be either xm, or sexpr (S-expression format).

-v, --verbose

Prints more detailed information about the import process.

Example C.1: Converting Xen Domain Configuration to libvirt

Suppose you have a Xen domain managed with xm with the following configuration saved in /etc/xen/sle12.xm:

kernel = "/boot/vmlinuz-2.6-xenU"
  memory = 128
  name = "SLE12"      
  root = "/dev/hda1 ro"
  disk = [ "file:/var/xen/sle12.img,hda1,w" ]

Convert it to libvirt XML without importing it, and look at its content:

# xen2libvirt -f xm -c /etc/xen/sle12.xm > /etc/libvirt/qemu/sles12.xml
  # cat /etc/libvirt/qemu/sles12.xml
  <domain type='xen'>
  <name>SLE12</name>
  <uuid>43e1863c-8116-469c-a253-83d8be09aa1d</uuid>
  <memory unit='KiB'>131072</memory>
  <currentMemory unit='KiB'>131072</currentMemory>
  <vcpu placement='static'>1</vcpu>
  <os>
  <type arch='x86_64' machine='xenpv'>linux</type>
  <kernel>/boot/vmlinuz-2.6-xenU</kernel>
  </os>
  <clock offset='utc' adjustment='reset'/>
  <on_poweroff>destroy</on_poweroff>
  <on_reboot>restart</on_reboot>
  <on_crash>restart</on_crash>
  <devices>
  <disk type='file' device='disk'>
  <driver name='file'/>
  <source file='/var/xen/sle12.img'/>
  <target dev='hda1' bus='xen'/>
  </disk>
  <console type='pty'>
  <target type='xen' port='0'/>
  </console>
  </devices>
  </domain>

To import the domain into libvirt, you can either run the same xen2libvirt command without the -c option, or use the exported file /etc/libvirt/qemu/sles12.xml and define a new Xen domain using virsh:

# sudo virsh define /etc/libvirt/qemu/sles12.xml

C.3 Differences Between the xm and xl Applications

  • Filename: xm_vs_xl.xml
  • ID: sec.xmvsxl

The purpose of this chapter is to list all differences between xm and xl applications. Generally, xl is designed to be compatible with xm. Replacing xm with xl in custom scripts or tools is usually sufficient.

You can also use the libvirt framework using the virsh command. In this documentation only the first OPTION for virsh will be shown. To get more help on this option do a:

virsh help OPTION

C.3.1 Notation Conventions

To easily understand the difference between xl and xm commands, the following notation is used in this section:

Table C.1: Notation Conventions

Notation

Meaning

(-) minus

Option exists in xm, but xl does not include it.

(+) plus

Option exists in xl, but xm does not include it.

C.3.2 New Global Options

Table C.2: New Global Options

Options

Task

(+) -v

Verbose, increase the verbosity of the output

(+) -N

Dry run, do not actually execute the command

(+) -f

Force execution. xl will refuse to run some commands if it detects that xend is also running, this option will force the execution of those commands, even though it is unsafe

C.3.3 Unchanged Options

List of common options of xl and xm, and their libvirt equivalents.

Table C.3: Common Options

Options

Task

libvirt equivalent

destroy DOMAIN

Immediately terminate the domain.

virsh destroy

domid DOMAIN_NAME

Convert a domain name to a DOMAIN_ID.

virsh domid

domname DOMAIN_ID

Convert a DOMAIN_ID to a DOMAIN_NAME.

virsh domname

help

Display the short help message (that is, common commands).

virsh help

pause DOMAIN_ID

Pause a domain. When in a paused state, the domain will still consume allocated resources such as memory, but will not be eligible for scheduling by the Xen hypervisor.

virsh suspend

unpause DOMAIN_ID

Move a domain out of the paused state. This will allow a previously paused domain to be eligible for scheduling by the Xen hypervisor.

virsh resume

rename DOMAIN_ID NEW_DOMAIN_NAME

Change the domain name of DOMAIN_ID to NEW_DOMAIN_NAME.

  1. virsh dumpxml DOMAINNAME >
              DOMXML
  2. modify the domain's name in DOMXML

  3. virsh undefine DOMAINNAME
  4. virsh define DOMAINNAME

sysrq DOMAIN <letter>

Send a Magic System Request to the domain, each type of request is represented by a different letter. It can be used to send SysRq requests to Linux guests, see https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html for more information. It requires PV drivers to be installed in your guest OS.

virsh send-keys can send Magic Sys Req only for KVM

vncviewer OPTIONS DOMAIN

Attach to domain's VNC server, forking a vncviewer process.

virt-view DOMAIN_ID

virsh VNCDISPLAY

vcpu-set DOMAIN_ID <vCPUs>

Enable the vcpu-count virtual CPUs for the domain in question. Like mem-set, this command can only allocate up to the maximum virtual CPU count configured at boot for the domain.

virsh setvcpus

vcpu-list DOMAIN_ID

List VCPU information for a specific domain. If no domain is specified, VCPU information for all domains will be provided.

virsh vcpuinfo

vcpu-pin DOMAIN_ID <VCPU|all> <CPUs|all>

Pin the VCPU to only run on the specific CPUs. The keyword all can be used to apply the CPU list to all VCPUs in the domain.

virsh vcpupin

dmesg [-c]

Read the Xen message buffer, similar to dmesg on a Linux system. The buffer contains informational, warning, and error messages created during Xen's boot process.

top

Execute the xentop command, which provides real time monitoring of domains. xentop is a curses interface.

virsh nodecpustats

virsh nodememstats

uptime [-s] DOMAIN

Print the current uptime of the domains running. With the xl command, the DOMAIN argument is mandatory.

debug-keys KEYS

Send debug keys to Xen. It is the same as pressing the Xen conswitch (Ctrl-A by default) three times and then pressing "keys".

cpupool-migrate DOMAIN CPU_POOL

Move a domain specified by DOMAIN_ID or DOMAIN into a CPU_POOL.

cpupool-destroy CPU_POOL

Deactivate a cpu pool. This is possible only if no domain is active in the cpu-pool.

block-detach DOMAIN_ID DevId

Detach a domain's virtual block device. devid may be the symbolic name or the numeric device id given to the device by Dom0. You will need to run xl block-list to determine that number.

virsh detach-disk

network-attach DOMAIN_ID NETWORK_DEVICE

Create a new network device in the domain specified by DOMAIN_ID. network-device describes the device to attach, using the same format as the vif string in the domain configuration file

virsh attach-interface

virsh attach-device

pci-attach DOMAIN <BDF> [Virtual Slot]

Hotplug a new pass-through PCI device to the specified domain. BDF is the PCI Bus/Device/Function of the physical device to be passed through.

virsh attach-device

pci-list DOMAIN_ID

List pass-through PCI devices for a domain

getenforce

Determine if the FLASK security module is loaded and enforcing its policy.

setenforce <1|0|Enforcing|Permissive>

Enable or disable enforcing of the FLASK access controls. The default is permissive and can be changed using the flask_enforcing option on the hypervisor's command line.

C.3.4 Removed Options

List of xm options which are no more available with the XL tool stack and a replacement solution if available.

C.3.4.1 Domain Management

The list of Domain management removed command and their replacement.

Table C.4: Domain Management Removed Options

Domain Management Removed Options

Options

Task

Equivalent

(-) log

Print the Xend log.

This log file can be found in /var/log/xend.log

(-) delete

Remove a domain from Xend domain management. The list option shows the domain names

virsh undefine

(-) new

Adds a domain to Xend domain management

virsh define

(-) start

Start a Xend managed domain that was added using the xm new command

virsh start

(-) dryrun

Dry run - prints the resulting configuration in SXP but does not create the domain

xl -N

(-) reset

Reset a domain

virsh reset

(-) domstate

Show domain state

virsh domstate

(-) serve

Proxy Xend XMLRPC over stdio

(-) resume DOMAIN OPTIONS

Moves a domain out of the suspended state and back into memory

virsh resume

(-) suspend DOMAIN

Suspend a domain to a state file so that it can be later resumed using the resume subcommand. Similar to the save subcommand although the state file may not be specified

virsh managedsave

virsh suspend

C.3.4.2 USB Devices

USB options are not available with xl/libxl tool stack. virsh has the attach-device and detach-device options but it does not work yet with USB.

Table C.5: USB Devices Management Removed Options

USB Devices Management Removed Options

Options

Task

(-) usb-add

Add a new USB physical bus to a domain

(-) usb-del

Delete a USB physical bus from a domain

(-) usb-attach

Attach a new USB physical bus to domain's virtual port

(-) usb-detach

Detach a USB physical bus from domain's virtual port

(-) usb-list

List domain's attachment state of all virtual port

(-) usb-list-assignable-devices

List all the assignable USB devices

(-) usb-hc-create

Create a domain's new virtual USB host controller

(-) usb-hc-destroy

Destroy a domain's virtual USB host controller

C.3.4.3 CPU Management

CPU management options has changed. New options are available, see: Section C.3.5.10, “xl cpupool-*

Table C.6: CPU Management Removed options

CPU Management Removed Options

Options

Task

(-) cpupool-new

Adds a CPU pool to Xend CPU pool management

(-) cpupool-start

Starts a Xend CPU pool

(-) cpupool-delete

Removes a CPU pool from Xend management

C.3.4.4 Other Options

Table C.7: Other Options

Other Removed Options

Options

Task

(-) shell

Launch an interactive shell

(-) change-vnc-passwd

Change vnc password

(-) vtpm-list

List virtual TPM devices

(-) block-configure

Change block device configuration

C.3.5 Changed Options

C.3.5.1 create

xl create CONFIG_FILE OPTIONS VARS

Note
Note: libvirt Equivalent:

virsh create

Table C.8: xl create Changed Options

create Changed Options

Options

Task

(*) -f=FILE, --defconfig=FILE

Use the given configuration file

Table C.9: xm create Removed Options

create Removed Options

Options

Task

(-) -s, --skipdtd

Skip DTD checking - skips checks on XML before creating

(-) -x, --xmldryrun

XML dry run

(-) -F=FILE, --config=FILE

Use the given SXP formatted configuration script

(-) --path

Search path for configuration scripts

(-) --help_config

Print the available configuration variables (vars) for the configuration script

(-) -n, --dryrun

Dry run — prints the configuration in SXP but does not create the domain

(-) -c, --console_autoconnect

Connect to the console after the domain is created

(-) -q, --quiet

Quiet mode

(-) -p, --paused

Leave the domain paused after it is created

Table C.10: xl create Added Options

create Added Options

Options

Task

(+) -V, --vncviewer

Attach to domain's VNC server, forking a vncviewer process

(+) -A, --vncviewer-autopass

Pass VNC password to vncviewer via stdin

C.3.5.2 console

xl console OPTIONS DOMAIN

Note
Note: libvirt Equivalent

virsh console

Table C.11: xl console Added Options

console Added Option

Option

Task

(+) -t [pv|serial]

Connect to a PV console or connect to an emulated serial console. PV consoles are the only consoles available for PV domains while HVM domains can have both

C.3.5.3 info

xl info

Table C.12: xm info Removed Options

info Removed Options

Options

Task

(-) -n, --numa

Numa info

(-) -c, --config

List Xend configuration parameters

C.3.5.4 dump-core

xl dump-core DOMAIN FILENAME

Note
Note: libvirt Equivalent

virsh dump

Table C.13: xm dump-core Removed Options

dump-core Removed Options

Options

Task

(-) -L, --live

Dump core without pausing the domain

(-) -C, --crash

Crash domain after dumping core

(-) -R, --reset

Reset domain after dumping core

C.3.5.5 list

xl list options DOMAIN

Note
Note: libvirt Equivalent

virsh list --all

Table C.14: xm list Removed Options

list Removed Options

Options

Task

(-) -l, --long

The output for xm list presents the data in SXP format

(-) --state==STATE

Output information for VMs in the specified state

Table C.15: xl list Added Options

list Added Options

Options

Task

(+) -Z, --context

Also prints the security labels

(+) -v, --verbose

Also prints the domain UUIDs, the shutdown reason and security labels

C.3.5.6 mem-*

Note
Note: libvirt Equivalent

virsh setmem

virsh setmaxmem

Table C.16: xl mem-* Changed Options

mem-* Changed Options

Options

Task

mem-max DOMAIN_ID MEM

Appending t for terabytes, g for gigabytes, m for megabytes,k for kilobytes and b for bytes. Specify the maximum amount of memory the domain can use.

mem-set DOMAIN_ID MEM

Set the domain's used memory using the balloon driver

C.3.5.7 migrate

xl migrate OPTIONS DOMAIN HOST

Note
Note: libvirt Equivalent

virsh migrate --live hvm-sles11-qcow2 xen+ CONNECTOR://USER@IP_ADDRESS/

Table C.17: xm migrate Removed Options

migrate Removed Options

Options

Task

(-) -l, --live

Use live migration. This will migrate the domain between hosts without shutting down the domain

(-) -r, --resource Mbs

Set maximum Mbs allowed for migrating the domain

(-) -c, --change_home_server

Change home server for managed domains

(-) --max_iters=MAX_ITERS

Number of iterations before final suspend (default:30)

(-) --max_factor=MAX_FACTOR

Max amount of memory to transfer before final suspend (default: 3*RAM).

(-) --min_remaining=MIN_REMAINING

Number of dirty pages before final suspend (default:50)

(-) --abort_if_busy

Abort migration instead of doing final suspend

(-) --log_progress

Log progress of migration to xend.log

(-) -s, --ssl

Use ssl connection for migration

Table C.18: xl migrate Added Options

migrate Added Options

Options

Task

(+) -s SSHCOMMAND

Use <sshcommand> instead of ssh

(+) -e

On the new host, do not wait in the background (on <host>) for the death of the domain

(+) -C CONFIG

Send <config> instead of a configuration file from creation

C.3.5.8 Domain Management

xl reboot OPTIONS DOMAIN

Note
Note: libvirt Equivalent

virsh reboot

Table C.19: xm reboot Removed Options

reboot Removed Options

Options

Task

(-) -a, --all

Reboot all domains

(-) -w, --wait

Wait for reboot to complete before returning. This may take a while, as all services in the domain need to be shut down cleanly

Table C.20: xl reboot Added Options

reboot Added Options

Option

Task

(+) -F

Fallback to ACPI reset event for HVM guests with no PV drivers

xl save OPTIONS DOMAIN CHECK_POINT_FILE CONFIG_FILE

Note
Note: libvirt Equivalent

virsh save

Table C.21: xl save Added Options

save Added Options

Option

Task

(+) -c

Leave domain running after creating the snapshot

xl restore OPTIONS CONFIG_FILE CHECK_POINT_FILE

Note
Note: libvirt Equivalent

virsh restore

Table C.22: xl restore Added Options

restore Added Options

Options

Task

(+) -p

Do not unpause domain after restoring it

(+) -e

Do not wait in the background for the death of the domain on the new host

(+) -d

Enable debug messages

(+) -V, --vncviewer

Attach to domain's VNC server, forking a vncviewer process

(+) -A, --vncviewer-autopass

Pass VNC password to vncviewer via stdin

xl shutdown OPTIONS DOMAIN

Note
Note: libvirt Equivalent

virsh shutdown

Table C.23: xm shutdown Removed Options

shutdown Removed Options

Options

Task

(-) -w, --wait

Wait for the domain to complete shutdown before returning

(-) -a

Shutdown all guest domains

(-) -R

(-) -H

Table C.24: xl shutdown Added Options

shutdown Added Options

Option

Task

(+) -F

If the guest does not support PV shutdown control then fallback to sending an ACPI power event

Table C.25: xl trigger Changed Options

trigger Changed Options

Option

Task

trigger DOMAIN <nmi|reset|init|power|sleep|s3resume> VCPU

Send a trigger to a domain. Only available for HVM domains

C.3.5.9 xl sched-*

xl sched-credit OPTIONS

Note
Note: libvirt Equivalent

virsh schedinfo

Table C.26: xm sched-credit Removed Options

sched-credit Removed Options

Options

Task

-d DOMAIN, --domain=DOMAIN

Domain

-w WEIGHT, --weight=WEIGHT

A domain with a weight of 512 will get twice as much CPU as a domain with a weight of 256 on a contended host. Legal weights range from 1 to 65535 and the default is 256

-c CAP, --cap=CAP

The CAP optionally fixes the maximum amount of CPU a domain can consume

Table C.27: xl sched-credit Added Options

sched-credit Added Options

Options

Task

(+) -p CPUPOOL, --cpupool=CPUPOOL

Restrict output to domains in the specified cpupool

(+) -s, --schedparam

Specify to list or set pool-wide scheduler parameters

(+) -t TSLICE, --tslice_ms=TSLICE

Timeslice tells the scheduler how long to allow VMs to run before pre-empting

(+) -r RLIMIT, --ratelimit_us=RLIMIT

Ratelimit attempts to limit the number of schedules per second

xl sched-credit2 OPTIONS

Note
Note: libvirt Status

virsh only supports credit scheduler, not credit2 scheduler

Table C.28: xm sched-credit2 Removed Options

sched-credit2 Removed Options

Options

Task

-d DOMAIN, --domain=DOMAIN

Domain

-w WEIGHT, --weight=WEIGHT

Legal weights range from 1 to 65535 and the default is 256

Table C.29: xl sched-credit2 Added Options

sched-credit2 Added Options

Option

Task

(+) -p CPUPOOL, --cpupool=CPUPOOL

Restrict output to domains in the specified cpupool

xl sched-sedf OPTIONS

Table C.30: xm sched-sedf Removed Options

sched-sedf Removed Options

Options

Task

-p PERIOD, --period=PERIOD

The normal EDF scheduling usage in milliseconds

-s SLICE, --slice=SLICE

The normal EDF scheduling usage in milliseconds

-l LATENCY, --latency=LATENCY

Scaled period if domain is doing heavy I/O

-e EXTRA, --extra=EXTRA

Flag for allowing domain to run in extra time (0 or 1)

-w WEIGHT, --weight=WEIGHT

Another way of setting CPU slice

Table C.31: xl sched-sedf Added Options

sched-sedf Added Options

Options

Task

(+) -c CPUPOOL, --cpupool=CPUPOOL

Restrict output to domains in the specified cpupool

(+) -d DOMAIN, --domain=DOMAIN

Domain

C.3.5.10 xl cpupool-*

xl cpupool-cpu-remove CPU_POOL <CPU nr>|node:<node nr>

xl cpupool-list [-c|--cpus] CPU_POOL

Table C.32: xm cpupool-list Removed Options

cpupool-* Removed Options

Option

Task

(-) -l, --long

Output all CPU pool details in SXP format

xl cpupool-cpu-add CPU_POOL cpu-nr|node:node-nr

xl cpupool-create OPTIONS CONFIG_FILE [Variable=Value ...]

Table C.33: xm cpupool-create Removed Options

cpupool-create Removed Options

Options

Task

(-) -f FILE, --defconfig=FILE

Use the given Python configuration script. The configuration script is loaded after arguments have been processed

(-) -n, --dryrun

Dry run - prints the resulting configuration in SXP but does not create the CPU pool

(-) --help_config

Print the available configuration variables (vars) for the configuration script

(-) --path=PATH

Search path for configuration scripts. The value of PATH is a colon-separated directory list

(-) -F=FILE, --config=FILE

CPU pool configuration to use (SXP)

C.3.5.11 PCI and Block Devices

xl pci-detach [-f] DOMAIN_ID <BDF>

Note
Note: libvirt Equivalent

virsh detach-device

Table C.34: xl pci-detach Added Options

pci-detach Added Options

Option

Task

(+) -f

If -f is specified, xl is going to forcefully remove the device even without guest's collaboration

Table C.35: xm block-list Removed Options

block-list Removed Options

Option

Task

(-) -l, --long

List virtual block devices for a domain

Table C.36: Other Options

Option

libvirt equivalent

xl block-attach DOMAIN <disk-spec-component(s)>

virsh attach-disk/attach-device

xl block-list DOMAIN_ID

virsh domblklist

C.3.5.12 Network

Table C.37: Network Options

Option

libvirt equivalent

xl network-list DOMAIN(s)

virsh domiflist

xl network-detach DOMAIN_ID devid|mac

virsh detach-interface

xl network-attach DOMAIN(s)

virsh attach-interface/attach-device

Table C.38: xl network-attach Removed Options

Removed Options

Option

Task

(-) -l, --long

C.3.6 New Options

Table C.39: New Options

Options

Task

config-update DOMAIN CONFIG_FILE OPTIONS VARS

Update the saved configuration for a running domain. This has no immediate effect but will be applied when the guest is next restarted. This command is useful to ensure that runtime modifications made to the guest will be preserved when the guest is restarted

migrate-receive

sharing DOMAIN

List count of shared pages.List specifically for that domain. Otherwise, list for all domains

vm-list

Prints information about guests. This list excludes information about service or auxiliary domains such as Dom0 and stubdoms

cpupool-rename CPU_POOL NEWNAME

Renames a cpu-pool to newname

cpupool-numa-split

Splits up the machine into one cpu-pool per numa node

cd-insert DOMAIN <VirtualDevice> <type:path>

Insert a CD-ROM into a guest domain's existing virtual CD drive. The virtual drive must already exist but can be current empty

cd-eject DOMAIN <VirtualDevice>

Eject a CD-ROM from a guest's virtual CD drive. Only works with HVM domains

pci-assignable-list

List all the assignable PCI devices. These are devices in the system which are configured to be available for pass-through and are bound to a suitable PCI back-end driver in Dom0 rather than a real driver

pci-assignable-add <BDF>

Make the device at PCI Bus/Device/Function BDF assignable to guests.This will bind the device to the pciback driver

pci-assignable-remove OPTIONS <BDF>

Make the device at PCI Bus/Device/Function BDF assignable to guests. This will at least unbind the device from pciback

loadpolicy POLICY_FILE

Load FLASK policy from the given policy file. The initial policy is provided to the hypervisor as a multiboot module; this command allows runtime updates to the policy. Loading new security policy will reset runtime changes to device labels

C.5 Saving a Xen Guest Configuration in an xm Compatible Format

Although xl is now the current toolkit for managing Xen guests (apart from the preferred libvirt), you may need to export the guest configuration to the previously used xm format. To do this, follow these steps:

  1. First export the guest configuration to a file:

    virsh dumpxml guest_id > guest_cfg.xml
  2. Then convert the configuration to the xm format:

    virsh domxml-to-native xen-xm guest_cfg.xml > guest_xm_cfg

D Documentation Updates

  • Filename: virt_docupdates.xml
  • ID: app.virt.docupdates

This chapter lists content changes for this document.

This manual was updated on the following dates:

D.1 ??? 2018 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)

Chapter 14, Configuring Virtual Machines
Bugfixes

D.2 October 2017 (Maintenance Release of SUSE Linux Enterprise Server 12 SP3)

Bugfixes

D.3 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)

General
Chapter 9, Guest Installation
Chapter 14, Configuring Virtual Machines
Chapter 27, Setting Up a KVM VM Host Server
Chapter 29, Running Virtual Machines with qemu-system-ARCH
Chapter 31, Linux Containers
Bugfixes

D.4 November 2016 (Release of SUSE Linux Enterprise Server 12 SP2)

General
  • The e-mail address for documentation feedback has changed to doc-team@suse.com.

  • The documentation for Docker has been enhanced and renamed to Docker Guide.

General Changes to this Guide
Chapter 5, Virtualization Tools
Chapter 7, Supported Guests, Hosts and Features
Chapter 10, Basic VM Guest Management
Chapter 11, Connecting and Authorizing
Chapter 13, Managing Networks
Chapter 14, Configuring Virtual Machines
Chapter 16, VM Guest Clock Settings
Chapter 17, libguestfs
Chapter 18, Setting Up a Virtual Machine Host
Chapter 20, Managing a Virtualization Environment
Chapter 21, Block Devices in Xen
Chapter 29, Running Virtual Machines with qemu-system-ARCH

D.5 March 2016 (Maintenance Release of SUSE Linux Enterprise Server 12 SP1)

Chapter 7, Supported Guests, Hosts and Features

D.6 December 2015 (Initial Release of SUSE Linux Enterprise Server 12 SP1)

General
  • SMT Guide is now part of the documentation for SUSE Linux Enterprise Server.

  • Add-ons provided by SUSE have been renamed as modules and extensions. The manuals have been updated to reflect this change.

  • Numerous small fixes and additions to the documentation, based on technical feedback.

  • The registration service has been changed from Novell Customer Center to SUSE Customer Center.

  • In YaST, you will now reach Network Settings via the System group. Network Devices is gone (https://bugzilla.suse.com/show_bug.cgi?id=867809).

General
  • Added Chapter 13, Managing Networks.

  • Rewrote large parts of the PCI Pass-Through documentation since KVM PCI Pass-Through has been replaced by VFIO.

Chapter 7, Supported Guests, Hosts and Features
  • Updated the lists of supported VM Guests and VM Host Servers (Fate #319284 and #319285).

Chapter 10, Basic VM Guest Management
Chapter 12, Managing Storage
Chapter 14, Configuring Virtual Machines
Chapter 19, Virtual Networking
Chapter 23, Administrative Tasks
Chapter 27, Setting Up a KVM VM Host Server
Chapter 29, Running Virtual Machines with qemu-system-ARCH
Bugfixes

D.7 February 2015 (Documentation Maintenance Update)

Bugfixes

D.8 October 2014 (Initial Release of SUSE Linux Enterprise Server 12)

General
  • Removed all KDE documentation and references because KDE is no longer shipped.

  • Removed all references to SuSEconfig, which is no longer supported (Fate #100011).

  • Move from System V init to systemd (Fate #310421). Updated affected parts of the documentation.

  • YaST Runlevel Editor has changed to Services Manager (Fate #312568). Updated affected parts of the documentation.

  • Removed all references to ISDN support, as ISDN support has been removed (Fate #314594).

  • Removed all references to the YaST DSL module as it is no longer shipped (Fate #316264).

  • Removed all references to the YaST Modem module as it is no longer shipped (Fate #316264).

  • Btrfs has become the default file system for the root partition (Fate #315901). Updated affected parts of the documentation.

  • The dmesg now provides human-readable time stamps in ctime()-like format (Fate #316056). Updated affected parts of the documentation.

  • syslog and syslog-ng have been replaced by rsyslog (Fate #316175). Updated affected parts of the documentation.

  • MariaDB is now shipped as the relational database instead of MySQL (Fate #313595). Updated affected parts of the documentation.

  • SUSE-related products are no longer available from http://download.novell.com but from http://download.suse.com. Adjusted links accordingly.

  • Novell Customer Center has been replaced with SUSE Customer Center. Updated affected parts of the documentation.

  • /var/run is mounted as tmpfs (Fate #303793). Updated affected parts of the documentation.

  • The following architectures are no longer supported: IA64 and x86. Updated affected parts of the documentation.

  • The traditional method for setting up the network with ifconfig has been replaced by wicked. Updated affected parts of the documentation.

  • A lot of networking commands are deprecated and have been replaced by newer commands (usually ip). Updated affected parts of the documentation.

    arp: ip neighbor
    ifconfig: ip addr, ip link
    iptunnel: ip tunnel
    iwconfig: iw
    nameif: ip link, ifrename
    netstat: ss, ip route, ip -s link, ip maddr
    route: ip route
  • Numerous small fixes and additions to the documentation, based on technical feedback.

Part I, “Introduction”
Chapter 8, Starting and Stopping libvirtd
  • Added introductory paragraph on virt-install.

Chapter 9, Guest Installation
Chapter 12, Managing Storage
Chapter 14, Configuring Virtual Machines
Chapter 10, Basic VM Guest Management
Part IV, “Managing Virtual Machines with Xen”
  • Migrated from Xend/xm toolkit to xl.

Chapter 22, Virtualization: Configuration Options and Settings
Chapter 28, Guest Installation
Chapter 29, Running Virtual Machines with qemu-system-ARCH
Chapter 30, Virtual Machine Administration Using QEMU Monitor
Part VI, “Managing Virtual Machines with LXC”
Bugfixes
SUSE Linux Enterprise Server 12 SP3

Docker Guide

This guide introduces Docker, a lightweight virtualization solution to run virtual units simultaneously on a single control host.

Publication Date: April 04, 2018

Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

1 Docker Overview

  • Filename: docker_overview.xml
  • ID: cha.docker.overview

Docker is a lightweight virtualization solution to run multiple virtual units (containers) simultaneously on a single control host. Containers are isolated with Kernel Control Groups ( Control groups ) and Namespace .

Full virtualization solutions such as Xen, KVM, or libvirt are based on the processor simulating a complete hardware environment and controlling the virtual machines. However, Docker only provides operating system-level virtualization where the Linux kernel controls isolated containers.

Before going into detail about Docker, let's define some of the terms used:

Docker engine

The docker engine is a server-client type application that performs all tasks related to virtual machines. The Docker engine comprises the following:

  • daemon - is the server side of the docker engine that manages all docker objects (images, containers, network used by containers, etc.)

  • REST API - applications can use this API to communicate directly with the daemon

  • a CLI client - that enables you to communicate with the daemon. If the daemon is running on a different machine than the CLI client, the CLI client can communicate by using network sockets or the REST API provided by the docker engine.

Image

An image is a read-only template used to create a virtual machine on the host server. A Docker image is made by a series of layers built one over the other. Each layer corresponds to a permanent change, for example an update of an application. The changes are stored in a file called a dockerfile. For more details see the official Docker documentation.

Dockerfile

A dockerfile stores changes made on top of the base image. The Docker engine reads instructions in the dockerfile and builds a new image according to the instructions.

Container

A container is a running instance based on a particular Docker Image. Each container can be distinguished by a unique container ID.

Registry

A registry is storage for already created images. It typically contains several repositories There are two types of registry:

  • public registry - where everyone (usually registered) can download and use images. A typical public registry is Docker Hub.

  • private registry - these are accessible for particular users or from a particular private network.

Repository

A repository is storage in a registry that stores a different version of a particular image. You can pull or push images from or to a repository.

Control groups

Control groups, also called cgroups, is a Linux kernel feature that allows aggregating or partitioning tasks (processes) and all their children into hierarchically organized groups to isolate resources.

Namespace

Docker uses namespaces for its containers that isolates resources reserved for particular containers.

Orchestration

In a production environment you typically need a cluster with many containers on each cluster node. The containers must cooperate and you need a framework that enables you to manage the containers automatically. The act of automatic container management is called container orchestration and is typically handled by Kubernetes.

Docker is a platform that allows developers and system administrators to manage the complete life cycle of images. Docker makes it easy to build, ship and run images containing applications.

Docker provides you with the following advantages:

  • Isolation of applications and operating systems through containers.

  • Near native performance, as Docker manages allocation of resources in real time.

  • Controls network interfaces and resources available inside containers through cgroups.

  • Versioning of images.

  • Allows building new images based on existing ones.

  • Provides you with container orchestration.

On the other hand, Docker has the following limitations:

Limitations of Docker
  • Containers run inside the host system's kernel and cannot use a different kernel.

  • Only allows Linux guest operating systems.

  • Docker is not a full virtualization stack like Xen, KVM, or libvirt.

  • Security depends on the host system. Refer to the official security documentation for more details.

1.1 Docker Architecture

Docker uses a client/server architecture. You can use the CLI client to communicate with the daemon. The daemon then performs operations with containers and manages images locally or in registry. The CLI client can run on the same server as the host daemon or on a different machine. The CLI client communicates with the daemon by using network sockets. The architecture is depicted in Figure 1.1, “The docker architecture”.

The docker architecture
Figure 1.1: The docker architecture

1.2 Docker Drivers

1.2.1 Container Drivers

Docker uses libcontainer as the back-end driver to handle containers.

1.2.2 Storage Drivers

Docker supports different storage drivers:

  • vfs: this driver is automatically used when the Docker host file system does not support copy-on-write. This is a simple driver which does not offer some advantages of Docker (like sharing layers, more on that in the next sections). It is highly reliable but also slow.

  • devicemapper: this driver relies on the device-mapper thin provisioning module. It supports copy-on-write, hence it offers all the advantages of Docker.

  • btrfs: this driver relies on Btrfs to provide all the features required by Docker. To use this driver the /var/lib/docker directory must be on a Btrfs file system.

  • AUFS: this driver relies on the AUFS union file system. Neither the upstream kernel nor the SUSE one supports this file system. Hence the AUFS driver is not built into the SUSE Docker package.

SLE 12 uses the Btrfs file system by default, which leads Docker to use the btrfs driver.

It is possible to specify which driver to use by changing the value of the DOCKER_OPTS variable defined inside of the /etc/sysconfig/docker file. This can be done either manually or using YaST by browsing to System › /etc/sysconfig Editor › System › Management › DOCKER_OPTS menu and entering the -s storage_driver string.

For example, to force the usage of the devicemapper driver enter the following text:

DOCKER_OPTS="-s devicemapper"
Important
Important: Mounting /var/lib/docker

It is recommended to have /var/lib/docker mounted on a separate partition or volume to not affect the Docker host operating system in case of a file system corruption.

In case you choose the Btrfs file system for /var/lib/docker, it is strongly recommended to create a subvolume for it. This ensures that the directory is excluded from file system snapshots. If not excluding /var/lib/docker from snapshots, the file system will likely run out of disk space soon after you start deploying containers. What's more, a rollback to a previous snapshot will also reset the Docker database and images. Refer to Creating and Mounting New Subvolumes at https://www.suse.com/documentation/sles-12/book_sle_admin/data/sec_snapper_setup.html for details.

2 Docker Installation

  • Filename: docker_installation.xml
  • ID: cha.docker.installation

2.1 General Preparation

Prepare the host as described below. Before installing any Docker-related packages, you need to enable the container module:

Note
Note: Built-in Docker Orchestration Support

Starting with Docker 1.12 the container orchestration is now an integral part of the Docker engine. Even though this feature is available in SLESSP1 and in SLESSP2, it is not supported and is only a technical preview. Use Kubernetes for Docker container orchestration, for details refer to the Kubernetes documentation.

Procedure 2.1: Enabling the Container Module Using YaST
  1. Start YaST, and select Software ›  Software Repositories.

  2. Click Add to open the add-on dialog.

  3. Select Extensions and Modules from Registration Server and click Next.

  4. From the list of available extensions and modules, select Container Module 12 x86_64 and click Next.

    The containers module and its repositories will be added to your system.

  5. If you use Subscription Management Tool, update the list of repositories on the SMT server.

Procedure 2.2: Enabling the Container Module Using SUSEConnect
  • The Container Module can be added also with the following command:

    $ sudo SUSEConnect -p sle-module-containers/12/x86_64 -r ''
    Note
    Note: Note about the SUSEConnect syntax

    The -r '' flag is required to avoid a known limitation of SUSEConnect.

Procedure 2.3: Installing and Setting Up Docker
  1. Install the docker package:

    sudo zypper install docker
  2. To automatically start the Docker service at boot time:

    sudo systemctl enable docker.service

    This will automatically enable docker.socket in consequence.

  3. In case you will use Portus and an SSL secured registry, open the /etc/sysconfig/docker file. Search for the parameter DOCKER_OPTS and add --insecure-registry ADDRESS_OF_YOUR_REGISTRY.

  4. In the production environment when using the SSL secured registry with Portus, add CA certificates to the directory /etc/docker/certs.d/<registry address> and copy the CA certificates to your system:

        sudo cp CA /etc/pki/trust/anchors/ && update-ca-certificates
  5. Start the Docker service:

    sudo systemctl start docker.service

    This will automatically start docker.socket in consequence.

The Docker daemon listens on a local socket which is accessible only by the root user and by the members of the docker group. The docker group is automatically created at package installation time. To allow a certain user to connect to the local Docker daemon, use the following command:

sudo /usr/sbin/usermod -aG docker USERNAME

The user can communicate with the local Docker daemon upon his next login.

2.2 Networking

If you want your containers to be able to access the external network, you must enable the ipv4 ip_forward rule. This can be done using YaST by browsing to System › Network Settings › Routing menu and ensuring Enable IPv4 Forwarding is checked.

This option cannot be changed when networking is handled by the Network Manager. In such cases the /etc/sysconfig/SuSEfirewall2 file needs to be edited manually to ensure the FW_ROUTE flag is set to yes:

FW_ROUTE="yes"

2.2.1 Networking Limitations on Power Architecture

Currently Docker networking has two limitations on the Power architecture.

The first limitation is about iptables. SLE 12 machines cannot run Docker with the iptables support enabled. An update of the kernel is going to solve this issue. In the meantime the Docker package for Power has iptables support disabled via a dedicated directive inside of /etc/sysconfig/docker.

As a result of this limitation Docker containers will not have access to the outer network. A possible workaround is to share the same network namespace between the host and the containers. This however reduces the isolation of the containers.

The network namespace of the host can be shared on a per-container basis by adding --net=host to the docker run command.

Note
Note: iptables support on SLE 12 SP1

SLE 12 SP1 hosts are not affected by this limitation but, given they use the same SLE 12 package, they will have iptables support disabled. This can be changed by removing the -iptables=false setting inside of /etc/sysconfig/docker.

The second limitation is about network isolation between the containers and the host. Currently it is not possible to prevent containers from probing or accessing arbitrary ports of each other.

3 Installing sle2docker

  • Filename: docker_sle2docker.xml
  • ID: cha.sle2docker.installation

The sle2docker is used to import pre-built SUSE Linux Enterprise images. The imported pre-built images can then be used to create base Docker images.

The tool is part of the official container module. You can install it by using zypper. But prior to installing sle2docker, verify that the following prerequisites are fulfilled:

  • Ruby is installed on the host machine.

  • The docker daemon is running on the system.

  • The user invoking sle2docker must have proper rights to invoke Docker commands.

If the conditions above are fulfilled, you can install the sle2docker tool by running:

sudo zypper in sle2docker

4 Storing Images

  • Filename: docker_registry.xml
  • ID: cha.registry.installation

Prior to creating your own images, you should decide where you will store the images. The easiest solution would be to push these images to the Docker Hub. By default all images pushed to the Docker Hub are public. This is probably fine as long as this does not violate your company's policy and your images do not contain sensitive data or proprietary software.

If you need to restrict access to your Docker images, there are two options:

  • Get a subscription on Docker Hub that unlocks the feature to create private repositories.

  • Run an on-site Docker registry where to store all the Docker images used by your organization or company and combine them with Portus to secure the registry.

This chapter describes how to set up an on-site Docker registry and how to combine it with Portus.

4.1 What is a Docker Registry?

The Docker registry is an open source project created by Docker Inc. It allows the storage and retrieval of Docker images. By running a local instance of the Docker registry it is possible to completely avoid usage of the Docker Hub.

The Docker registry is also used by the Docker Hub. However, the Docker Hub, as seen from the user perspective, is made of the following parts at least:

  • The user interface (UI): The part that is accessed by users with their browser. The UI provides a nice and intuitive way to browse the contents of the Docker Hub either manually or by using a search feature. It also allows to create organizations made by different users.

    This component is closed source.

  • The authentication component: This is used to protect the images stored inside of the Docker Hub. It validates all push, pull and search requests.

    This component is closed source.

  • The storage back-end: This is where the Docker images are sent and downloaded from. It is provided by the Docker registry.

    This component is open source.

4.2 Installing and Setting Up Docker Registry

  1. Install the docker-distribution-registry package:

    sudo zypper install docker-distribution-registry
  2. To automatically start the Docker registry at boot time:

    sudo systemctl enable registry
  3. Start the Docker registry:

    sudo systemctl start registry

The Docker registry configuration is defined inside of /etc/registry/config.yml.

With the default configuration the registry listens on ports 5000 and stores the Docker images under /var/lib/docker-registry.

Note
Note: Incompatible Versions of Docker and Docker Registry

Docker registry version 2.3 is not compatible with Docker versions older than 1.10, because v2 manifests were only introduced with Docker 1.10. As Docker and Docker registry can be installed on different boxes, the versions might be incompatible. If you experience communication errors between Docker and Docker registry, update both to the latest versions.

For more details about Docker registry and its configuration, see the official documentation at: https://docs.docker.com/registry/.

4.3 Limitations

The Docker registry has two major limitations:

  • It lacks any form of authentication. That means everybody with access to the Docker registry can push and pull images to it. That also includes the possibility to overwrite already existing images.

  • There is no way to see which images have been pushed to the Docker registry. You can manually take notes of what is being stored inside of it. There is also no search functionality, which makes collaboration harder.

The next section is going to introduce Portus, the solution to all of the problems above.

4.4 Portus

Portus is an authentication service and user interface for the Docker registry. It is an open source project created by SUSE to address all the limitations faced by the local instances of Docker registry.

By combining Portus and Docker registry, it is possible to have a secure and enterprise ready on-premise version of the Docker Hub.

Portus is accessible for SLE 12 customers through the Containers module. To install Portus, use the following command:

sudo zypper in portus

In order to configure Portus properly, follow these steps:

  1. First of all, you should install Portus's dependencies if you haven't already. This is thoroughly documented here: http://port.us.org/docs/setups/1_rpm_packages.html#portus-dependencies. This document will help you to get through the installation process, and it will also warn you about some of the common pitfalls.

  2. After installing Portus and its dependencies, you need to configure your instance. The initial setup of Portus is explained here: http://port.us.org/docs/setups/1_rpm_packages.html#initial-setup. When you are done with portusctl, you should modify some configurable values before using Portus. This is thoroughly explained in this documentation page: http://port.us.org/docs/Configuring-Portus.html.

  3. To apply the configuration changes, restart Apache (this is required after each configuration change).

  4. Finally, when entering Portus for the first time, you will be required to enter some information about your installed registry. For details, see: http://port.us.org/docs/setups/1_rpm_packages#the-default-installation.html.

  5. The Portus setup is now complete and you can start using Portus.

Currently, Portus is part of SUSE's Docker offer as a technology preview. For more information and documentation about Portus, see: http://port.us.org/.

5 Creating Custom Images

  • Filename: docker_building_images.xml
  • ID: docker.building.images

For creating your custom image you need a base docker image of SLES. You can use any of the pre-built SLES images that you can obtain as described in Section 5.2, “Customizing SLES Docker Images”.

Note
Note: No SLES Images in Docker Hub

Usually you can pull a variety of base docker images from the docker hub but that does not apply for SLES. Currently we cannot distribute SLES images for Docker because there is no way to associate an End-User License Agreement (EULA) to a Docker image. sle2docker enables you to import pre-built SLES images that you can use for creating base SLES images.

After you obtain your base docker image, you can modify the image by using a Dockerfile (usually placed in the build directory). Then use the standard docker building tool to create your custom image:

         docker build path_to_build_directory

For more docker build options please refer to the official Docker documentation.

Note
Note: Dockerizing Your Applications

You may want to write a dockerfile for your own application that should be run inside a docker container. For a procedure refer to Chapter 6, Dockerizing Applications.

5.1 Obtaining Base SLES Images

You can install pre-built images of SLES by using Zypper:

        sudo zypper in sles11sp4-docker-image suse-sles12sp3-image

Pre-built images do not have repositories configured. But when the Docker host has an SLE subscription that provides access to the product used in the image, Zypper will automatically have access to the right repositories.

After the pre-built images are installed, you need to list them using sle2docker to get a proper image name:

        sle2docker list

Now you need to activate the pre-built images:

        sle2docker activate PRE-BUILT_IMAGE_NAME

After successful activation, sle2docker will display the name of the docker image. You can customize the docker image as described in Section 5.2, “Customizing SLES Docker Images”.

5.2 Customizing SLES Docker Images

The pre-built images do not have any repository configured and do not include any modules or extensions. They contain a zypper service that contacts either the SUSE Customer Center (SCC) or your Subscription Management Tool (SMT) server, according to the configuration of the SLE host that runs the Docker container. The service obtains the list of repositories available for the product used by the Docker image. You can also directly declare extensions in your Dockerfile (for details refer to Section 5.2.3, “Adding SLE Extensions and Modules to Images”.

You do not need to add any credentials to the Docker image because the machine credentials are automatically injected into the container by the docker daemon. They are injected inside of the /run/secrets directory. The same applies to the /etc/SUSEConnect file of the host system, which is automatically injected into the /run/secrets directory.

Note
Note: Credentials and Security

The contents of the /run/secrets directory are never committed to a Docker image, hence there is no risk of your credentials leaking.

To obtain the list of repositories use the following command:

zypper ref -s

It will automatically add all the repositories to your container. For each repository added to the system a new file will be created under /etc/zypp/repos.d. The URLs of these repositories include an access token that automatically expires after 12 hours. To renew the token call the zypper ref -s command. It is secure to commit these files to a Docker image.

If you want to use a different set of credentials, place a custom /etc/zypp/credentials.d/SCCcredentials file inside of the Docker image. It contains the machine credentials that have the subscription you want to use. The same applies to the SUSEConnect file: to override the file available on the host system that is running the Docker container, add a custom /etc/SUSEConnect file inside of the Docker image.

Now you can create a custom Docker image by using a Dockerfile. If you want to create a custom SLE 12 image, please refer to Section 5.2.1, “Creating a Custom SLE 12 Image”. If you want to create a custom SLE 11 SP3 Docker image, please refer to Section 5.2.2, “Creating a Custom SLE 11 SP3 Image”. In case you would like to move your application to a Docker container, please refer to Chapter 6, Dockerizing Applications.

5.2.1 Creating a Custom SLE 12 Image

The following Docker file creates a simple Docker image based on SLE 12 SP3:

FROM suse/sles12sp3:latest

RUN zypper ref -s
RUN zypper -n in vim

When the Docker host machine is registered against an internal SMT server, the Docker image requires the SSL certificate used by SMT:

FROM suse/sles12sp3:latest

# Import the crt file of our private SMT server
ADD http://smt.test.lan/smt.crt /etc/pki/trust/anchors/smt.crt
RUN update-ca-certificates

RUN zypper ref -s
RUN zypper -n in vim

5.2.2 Creating a Custom SLE 11 SP3 Image

The following Docker file creates a simple Docker image based on SLE 11 SP4:

FROM suse/sles11sp3:latest

RUN zypper ref -s
RUN zypper -n in vim

When the Docker host machine is registered against an internal SMT server, the Docker image requires the SSL certificate used by SMT:

FROM suse/sles11sp4:latest

# Import the crt file of our private SMT server
ADD http://smt.test.lan/smt.crt /etc/ssl/certs/smt.pem
RUN c_rehash /etc/ssl/certs

RUN zypper ref -s
RUN zypper -n in vim

5.2.3 Adding SLE Extensions and Modules to Images

You may have subscriptions to SLE extensions or modules that you would like to use in your custom image. To add them to the Docker image, proceed as follows:

Procedure 5.1: Adding Extension and Modules
  1. Add the following into your Dockerfile:

    ADD *.repo /etc/zypp/repos.d/
    ADD *.service /etc/zypp/services.d
    RUN zypper refs && zypper refresh
  2. Copy all .service and .repo files that you will use into the directory where you will build the Docker image from the Dockerfile.

6 Dockerizing Applications

  • Filename: docker_dockerizing_application.xml
  • ID: docker.dockerizing.application

Docker is a technology that can help you to minimize resources used to run or build your applications. There are several types of applications that are suitable to run inside a Docker container like daemons, Web pages or applications that expose ports for communication. You can use Docker for automation of building and deployment processes by adding the build process into a docker image, then building the image and then running containers based on that image.

Running your application inside a docker container provides you with the following advantages:

  • You can minimize the runtime environment of the application as you can add to the docker image of the application just the required processes and applications.

  • The image with your application is portable across machines also with different Linux host systems.

  • You can share the image of your application by using a repository.

  • You can use different versions of required packages in the container than the host system uses without having problems with dependencies.

  • You can run several instances of the same application that are completely independent from each other.

Using Docker for building of applications provides the following features:

  • You can prepare a complete building image.

  • Your build always runs in the same environment.

  • Your developers can test their code in the same environment as used in production.

  • You can set up an automated building process.

The following section provides you with examples and tips on how to dockerize your applications. Prior to reading further, make sure that you have activated your SLES base docker image as described in Section 5.1, “Obtaining Base SLES Images”.

6.1 Running an Application with Specific Package Versions

You may face a problem that your application uses a specific version of a package that is different from the package installed on the system that should run your application. You can modify your application to work with another version or you may create a Docker image with that particular package version. The following example of a Dockerfile shows an image based on a current version of SLES but with an older version of the example package

                FROM suse/sles12sp3:latest
                MAINTAINER Tux

                RUN zypper ref && zypper in -f example-1.0.0-0
                COPY application.rpm /tmp/

                RUN zypper --non-interactive in /tmp/application.rpm

                ENTRYPOINT ["/etc/bin/application"]

                CMD ["-i"]

Now you can build the image by running in the same directory as the Dockerfile resides:

                docker build --tag tux_application:latest .

The Dockerfile example shown above performs the following operations during the docker build:

  1. Updates the SLES repositories.

  2. Installs the desired version of the example package.

  3. Copies your application package to the image. The source RPM must be placed in the build context.

  4. Unpacks your application.

  5. The last two steps run your application after a container is started.

After a successful build of the tux_application image, you can start a container based on your new image:

                docker run -it --name application_instance tux_application:latest

You have created a container that runs a single instance of your application. Bear in mind that after closing the application, the Docker container exits as well.

6.2 Running Applications with Specific Configuration

You may need to run an application that is delivered in a standard package accessible through SLES repositories but you may need to use a different configuration or use specific environment variables. In case you would like to run several instances of the application with non-standard configuration, you can create your own image that will pass the custom configuration to the application.

An example with the example application follows:

                FROM suse/sles12sp3:latest

                RUN zypper ref && zypper --non-interactive in example

                ENV BACKUP=/backup

                RUN mkdir -p $BACKUP
                COPY configuration_example /etc/example/

                ENTRYPOINT ["/etc/bin/example"]

The above example Dockerfile results in the following operations:

  1. Refreshing of repositories and installation of the example.

  2. Sets a BACKUP environment variable (the variable persists to containers started from the image). You can always overwrite the value of the variable with a new one while running the container by specifying a new value.

  3. Creates the directory /backup.

  4. Copies the configuration_example to the image.

  5. Runs the example application.

Now you can build the image and after a successful build, you can run a container based on your image.

6.3 Sharing Data between an Application and the Host System

You may run an application that needs to share data between the application's container and the host file system. Docker enables you to do data sharing by using volumes. You can declare a mount point directly in the Dockerfile. But you cannot specify a directory on the host system in the Dockerfile as the directory may not be accessible at the build time. You can find the mounted directory in the /var/lib/docker/volumes/ directory on the host system.

Note
Note: Discarding Changes to the Directory to Be Shared

After you declare a mount point by using the VOLUME instruction, all your changes performed (by using the RUN instruction) to the directory will be discarded. After the declaration, the volume is part of a temporary container that is then removed after a successful build. In case you need to e.g. change permissions, perform the change before you declare the directory as a mount point in the Dockerfile.

You can specify a particular mount point on the host system when running a container by using the -v option:

                docker run -it --name testing -v /home/tux/data:/data sles12sp3:latest /bin/bash
Note
Note

Using the -v option overwrites the VOLUME instruction if you specify the same mount point in the container.

Now let's create an example image with a Web server that will read Web content from the host's file system. The Dockerfile could look as follows:

FROM suse/sles12sp3:latest

                RUN zypper ref && zypper --non-interactive in apache2

                COPY apache2 /etc/sysconfig/

                RUN chown -R admin /data

                EXPOSE 80

                VOLUME /data

                ENTRYPOINT ["apache2ctl"]

The example above installs the Apache Web server to the image and copies all your configuration to the image. The data directory will be owned by the admin user and will be used as a mount point to store your web pages.

6.4 Applications Running in the Background

Your application may need to run in the background as a daemon or as an application exposing ports for communication. In that case a typical Docker container may be run in background. Do not run your application in the container in the background as it may cause exiting of the container. Run the container in the background instead. An example Dockerfile for an application exposing a port looks as follows:

                FROM suse/sles12sp3:latest

                RUN zypper ref && zypper --non-interactive in postfix
                RUN mkdir -p /var/spool/mail

                COPY main.cf /etc/postfix/main.cf

                EXPOSE 25 587

                VOLUME ["/var/spool/mail"]
                ENTRYPOINT ["/usr/sbin/postfix"]

Now you can build your image. Docker performs the following operations according to the instructions in the Dockerfile:

  1. Docker refreshes repositories and installs the postfix mail server as it is not installed by default in the SLES docker image.

  2. The /var/spool/mailboxes directory is created in the file system of the image. The directory will store all mailboxes if you configure the mail server to store data in this directory.

  3. Here you copy a configuration file to the particular directory. Make sure that the main.cf is located in the same directory as the Dockerfile. Bear in mind that the configuration will be the same for all instance run in the future. In case you need a different configuration for each container, you will need to edit it after running the container.

  4. Each started container will expose the ports: 25 and 587. In case you will run several instances of this image on the same machine, you should define a specific host name for each container.

  5. The VOLUME instruction creates a mount point at the /var/spool/mail directory in the container.

  6. The last instructions runs the postfix mail server in the started container.

After a successful build, you can run a container based on the image:

                docker run -d --name mail_server -v /var/spool/mail:/var/spool/mail postfix:latest /bin/bash

The -d option runs the container in a detached mode and further communication by using the CLI will not be possible. To reattach the container run:

                docker attach <container identification>

7 Working with Containers

  • Filename: docker_containers.xml
  • ID: cha.working.with.containers

After you have created your images, you can start your containers based on that image. You can run an instance of the image by using the docker run command. The Docker engine then creates and starts the container. The command docker run takes several arguments:

  • A container name - it is recommended to name your container.

  • Specify a user to use in your container.

  • Define a mount point.

  • Specify a particular host name, etc.

The container typically exits if its main process finishes. For example, if your container starts a particular application, as soon as you quit the application, the container exits. You can start the container again by running:

docker start -ai <container name>

You may need to remove unused containers, you can achieve this by using:

docker rm <container name>

7.1 Linking Containers

Docker enables you to link containers together which allows for communication between containers on the same host server. If you use the standard networking model, you can link containers by using the --link option when running containers:

First create a container to link to:

docker run -d --name sles sles12sp3 /bin/bash

Then create a container that will link to the sles container:

docker run --link sles:sles sles12sp3 /bin/bash

The container that links to sles has defined environment variables that enable connecting to the linked container.

A Documentation Updates

  • Filename: docker_docupdates.xml
  • ID: app.docker.docupdates

This chapter lists content changes for this document.

This manual was updated on the following dates:

A.1 September 2017 (Initial Release of SUSE Linux Enterprise Server 12 SP3)

General
Chapter 1, Docker Overview
Bugfixes

A.2 November 2016 (Initial Release of SUSE Linux Enterprise Server 12 SP2)

General
  • The e-mail address for documentation feedback has changed to doc-team@suse.com.

  • The documentation for Docker has been enhanced and renamed to Docker Guide.

General Changes to this Guide
Bugfixes
SUSE Linux Enterprise Server 12 SP3

Quick Start Manuals

Publication Date: April 04, 2018

Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

SUSE Linux Enterprise Server 12 SP3

Installation Quick Start

SUSE Linux Enterprise Server 12 SP3

Lists the system requirements and guides you step-by-step through the installation of SUSE Linux Enterprise Server from DVD, or from an ISO image.

Use the following procedures to install a new version of SUSE® Linux Enterprise Server 12 SP3. This document gives a quick overview on how to run through a default installation of SUSE Linux Enterprise Server for the AMD64/Intel 64 architecture.

Publication Date: April 04, 2018

1 Welcome to SUSE Linux Enterprise Server

For more detailed installation instructions and deployment strategies, see the SUSE Linux Enterprise Server Documentation at http://www.suse.com/documentation/.

1.1 Minimum System Requirements

  • any AMD64/Intel* EM64T processor (32-bit processors are not supported)

  • 512 MB physical RAM (1 GB or more recommended)

  • 3.5 GB available disk space (more recommended)

  • 800 x 600 display resolution (1024 x 768 or higher recommended)

1.2 Installing SUSE Linux Enterprise Server

Use these instructions if there is no existing Linux system on your machine, or if you want to replace an existing Linux system.

  1. Insert the SUSE Linux Enterprise Server DVD into the drive, then reboot the computer to start the installation program. On machines with a traditional BIOS you will see the graphical boot screen shown below. On machines equipped with UEFI, a slightly different boot screen is used. Secure boot on UEFI machines is supported.

    Use F2 to change the language for the installer. A corresponding keyboard layout is chosen automatically. See Section 6.2.2.1, “The Boot Screen on Machines Equipped with Traditional BIOS” or Section 6.2.2.2, “The Boot Screen on Machines Equipped with UEFI” for more information about changing boot options.

  2. Select Installation on the boot screen, then press Enter. This boots the system and loads the SUSE Linux Enterprise Server installer.

  3. The Language and Keyboard Layout are initialized with the language settings you have chosen on the boot screen. Change them here, if necessary.

    Read the License Agreement. It is presented in the language you have chosen on the boot screen. License Translations are available. You need to accept the agreement by checking I Agree to the License Terms to install SUSE Linux Enterprise Server. Proceed with Next.

  4. A system analysis is performed, where the installer probes for storage devices, and tries to find other installed systems. If the network could not be automatically configured while starting the installation system, the Network Settings dialog opens.

    After at least one network interface has been configured you can register your system at the SUSE Customer Center (SCC). Enter the e-mail address associated with your SCC account and the registration code for SUSE Linux Enterprise Server. A successful registration is a prerequisite for getting product updates and being entitled to technical support. Proceed with Next.

    Tip
    Tip: Installing Product Patches at Installation Time

    If SUSE Linux Enterprise Server has been successfully registered at the SUSE Customer Center, you are asked whether to install the latest available online updates during the installation. If choosing Yes, the system will be installed with the most current packages without having to apply the updates after installation. Activating this option is recommended.

    Note
    Note: Release Notes

    From this point on, the Release Notes can be viewed from any screen during the installation process by selecting Release Notes.

  5. After the system is successfully registered, YaST lists modules and extensions that are available for SUSE Linux Enterprise Server from the SUSE Customer Center. The list contains free modules, such as the SUSE Linux Enterprise SDK, or extensions requiring a registration key that is liable for costs. Click an entry to see its description. Optionally select a module or extension for installation by activating its check mark. Proceed with Next.

    Extension Selection
  6. The Add-on Product dialog allows you to add additional software sources (so-called repositories) to SUSE Linux Enterprise Server, that are not provided by the SUSE Customer Center. Such add-on products may include third-party products and drivers or additional software for your system.

    Tip
    Tip: Adding Drivers During the Installation

    You can also add driver update repositories via the Add-On Products dialog. Driver updates for SUSE Linux Enterprise are provided at http://drivers.suse.com/. These drivers have been created via the SUSE SolidDriver Program.

    If you want to skip this step, proceed with Next. Otherwise activate I would like to Install an Add-on Product. Specify a media type, a local path or a network resource hosting the repository and follow the on-screen instructions.

    Check Download Repository Description Files to download the files describing the repository now. If deactivated, they will be downloaded after the installation has started. Proceed with Next and insert a medium if required. Depending on the product's content it may be necessary to accept additional license agreements. Proceed with Next. If you have chosen an add-on product requiring a registration key, you will be asked to enter it at the Extension and Module Registration Codes page.

  7. Choose the System Role that meets your requirements best. Select Default System for physical machines or virtual guests. For a virtualization host that can run other virtual machines, select KVM Virtualization Host or Xen Virtualization Host.

  8. Review the partition setup proposed by the system. If necessary, change it. You have the following options:

    Edit Proposal Settings

    Lets you change options for the proposed settings, but not the suggested partition layout itself.

    Create Partition Setup

    Select a disk to which to apply the proposal.

    Expert Partitioner

    Opens the Expert Partitioner described in Section 12.1, “Using the YaST Partitioner”.

    To accept the proposed setup without any changes, choose Next to proceed.

  9. Select the clock and time zone to use in your system. To manually adjust the time or to configure an NTP server for time synchronization, choose Other Settings. See Section 6.12, “Clock and Time Zone” for detailed information. Proceed with Next.

  10. To create a local user, type the first and last name in the User’s Full Name field, the login name in the Username field, and the password in the Password field.

    The password should be at least eight characters long and should contain both uppercase and lowercase letters and numbers. The maximum length for passwords is 72 characters, and passwords are case-sensitive.

    For security reasons it is also strongly recommended not to enable the Automatic Login. You should also not Use this Password for the System Administrator but rather provide a separate root password in the next installation step. Proceed with Next.

  11. Type a password for the system administrator account (called the root user).

    You should never forget the root password! After you entered it here, the password cannot be retrieved. See Section 6.14, “Password for the System Administrator root for more information. Proceed with Next.

  12. Use the Installation Settings screen to review and—if necessary—change several proposed installation settings. The current configuration is listed for each setting. To change it, click the headline. Some settings, such as firewall or SSH can directly be changed by clicking the respective links.

    Tip
    Tip: Remote Access

    Changes you can make here, can also be made later at any time from the installed system. However, if you need remote access directly after the installation, you should adjust the Firewall and SSH settings according to your needs.

    Software

    The default scope of software includes the base system and X Window with the GNOME desktop. Clicking Software opens the Software Selection and System Tasks screen, where you can change the software selection by selecting or deselecting patterns. Each pattern contains several software packages needed for specific functions (for example, Web and LAMP server or a print server). For a more detailed selection based on software packages to install, select Details to switch to the YaST Software Manager. See Chapter 13, Installing or Removing Software for more information.

    Booting

    This section shows the boot loader configuration. Changing the defaults is only recommended if really needed. Refer to Chapter 12, The Boot Loader GRUB 2 for details.

    Firewall and SSH

    By default, the Firewall is enabled with the active network interface configured for the external zone. See Section 15.4, “SuSEFirewall2” for configuration details.

    The SSH service is disabled by default, its port (22) is closed. Therefore logging in from remote is not possible by default. Click enable and open to toggle these settings.

    Kdump

    Kdump saves the memory image (core dump) to the file system in case the kernel crashes. This enables you to find the cause of the crash by debugging the dump file. Kdump is preconfigured and enabled by default. See Section 17.7, “Basic Kdump Configuration” for more information.

    Default Systemd Target and Services

    By default, the system boots into the graphical target, with network, multiuser and display manager support. Switch to multi-user if you do not need to log in via display manager.

    System

    View detailed hardware information by clicking System. In the resulting screen you can also change Kernel Settings—see Section 6.15.8, “System Information for more information.

  13. After you have finalized the system configuration on the Installation Settings screen, click Install. Depending on your software selection you may need to agree to license agreements before the installation confirmation screen pops up. Up to this point no changes have been made to your system. After you click Install a second time, the installation process starts.

  14. During the installation, the progress is shown in detail on the Details tab.

  15. After the installation routine has finished, the computer is rebooted into the installed system. Log in and start YaST to fine-tune the system. If you are not using a graphical desktop or are working from remote, refer to Chapter 5, YaST in Text Mode for information on using YaST from a terminal.

2 Legal Notice

  • Filename: common_copyright_quick.xml
  • ID: no ID found

Copyright© 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors, nor the translators shall be held liable for possible errors or the consequences thereof.

SUSE Linux Enterprise Server 12 SP3

Xen to KVM Migration Guide

SUSE Linux Enterprise Server 12 SP3

As the KVM virtualization solution is becoming more and more popular among server administrators, many of them need a path to migrate their existing Xen based environments to KVM. As of now, there are no mature tools to automatically convert Xen VMs to KVM. There is, however, a technical solution that helps convert Xen virtual machines to KVM. The following information and procedures help you to perform such a migration.

Publication Date: April 04, 2018
Important
Important: Migration Procedure Not Supported

The migration procedure described in this document is not fully supported by SUSE. We provide it as a guidance only.

1 Migration to KVM Using virt-v2v

This section contains information to help you import virtual machines from foreign hypervisors (such as Xen) to KVM managed by libvirt.

Tip
Tip: Microsoft Windows Guests

This section is focused on converting Linux guests. Converting Microsoft Windows guests using virt-v2v is the same as converting Linux guests, except in regards to handling the Virtual Machine Driver Pack (VMDP). Additional details on converting Windows guests with the VMDP can be found in the separate Virtual Machine Driver Pack documentation at https://www.suse.com/documentation/sle-vmdp-22/.

1.1 Introduction to virt-v2v

virt-v2v is a command line tool to convert VM Guests from a foreign hypervisor to run on KVM managed by libvirt. It enables paravirtualized virtio drivers in the converted virtual machine if possible. A list of supported operating systems and hypervisors follows:

Supported Guest Operating Systems
  • SUSE Linux Enterprise Server

  • openSUSE

  • RedHat Enterprise Linux

  • Fedora

  • Microsoft Windows Server 2003 and 2008

Supported Source Hypervisor
  • Xen

Supported Target Hypervisor
  • KVM (managed by libvirt)

1.2 Installing virt-v2v

The installation of virt-v2v is simple:

sudo zypper install virt-v2v

Remember that virt-v2v requires root privileges, so you need to run it either as root, or via sudo.

1.3 Preparing the Virtual Machine

Note
Note: Conditions for Skipping This Step

If running virt-v2v on SLES 12 SP1 or before, this step can be safely skipped. This step can also be ignored if the virtual machine is fully virtualized or if it runs on SLES 12 SP2 or later.

The Xen virtual machine must have default kernel installed. To ensure this, run zypper in kernel-default on the virtual machine.

1.4 Converting Virtual Machines to Run under KVM Managed by libvirt

virt-v2v converts virtual machines from the Xen hypervisor to run under KVM managed by libvirt. To learn more about libvirt and virsh, see Part II, “Managing Virtual Machines with libvirt. Additionally, all virt-v2v command line options are explained in the virt-v2v manual page (man 1 virt-v2v).

Before converting a virtual machine, make sure to complete the following steps:

Procedure 1: Preparing the Environment for the Conversion
  1. Create a new local storage pool.

    virt-v2v copies the storage of the source virtual machine to a local storage pool managed by libvirt (the original disk image remains unchanged). You can create the pool either with Virtual Machine Manager, or virsh. For more information, see Section 12.1, “Managing Storage with Virtual Machine Manager” and Section 12.2, “Managing Storage with virsh.

  2. Prepare the local network interface.

    Check that the converted virtual machine can use a local network interface on the VM Host Server. It is usually a network bridge. If it is not defined yet, create it with YaST › System › Network Settings › Add › Bridge.

    Note
    Note: Mappings of Network Devices

    Network devices on the source Xen host can be mapped during the conversion process to corresponding network devices on the KVM target host. For example, the Xen bridge br0 can be mapped to the KVM network default. Sample mappings can be found in /etc/virt-v2v.conf. To enable these mappings, modify the XML rule as necessary and ensure the section is not commented out with <!-- and --> markers. For example:

     <network type='bridge' name='br0'>
       <network type='network' name='default'/>
     </network>
    Tip
    Tip: No Network Bridge

    If there is no network bridge available, Virtual Machine Manager can optionally create it.

virt-v2v has the following basic command syntax:

virt-v2v -i INPUT_METHOD -os STORAGE_POOL SOURCE_VM
input_method

There are two input methods: libvirt or libvirtxml. See the SOURCE_VM parameter for more information.

storage_pool

The storage pool you already prepared for the target virtual machine.

source_vm

The source virtual machine to convert. It depends on the INPUT_METHOD parameter: For libvirt, specify the name of a libvirt domain. For libvirtxml, specify the path to an XML file containing a libvirt domain specification.

Note
Note: Conversion Time

Conversion of a virtual machine takes a lot of system resources, mainly for copying the whole disk image for a virtual machine. Converting a single virtual machine typically takes up to 10 minutes, although virtual machines using very large disk images can take much longer.

1.4.1 Conversion Based on the libvirt XML Description File

This section describes how to convert a local Xen virtual machine using the libvirt XML configuration file. This method is suitable if the host is already running the KVM hypervisor. Make sure that the libvirt XML file of the source virtual machine, and the libvirt storage pool referenced from it are available on the local host.

  1. Obtain the libvirt XML description of the source virtual machine.

    Tip
    Tip: Obtaining the XML Files

    To obtain the libvirt XML files of the source virtual machine, you must run the host OS under the Xen kernel. If you already rebooted the host to the KVM-enabled environment, reboot back to the Xen kernel, dump the libvirt XML file, and then reboot back to the KVM environment.

    First identify the source virtual machine under virsh:

    root # virsh list
     Id    Name                           State
    ----------------------------------------------------
    [...]
      2     sles12_xen                     running
    [...]

    sles12_xen is the source virtual machine to convert. Now export its XML and save it to sles12_xen.xml:

    root # virsh dumpxml sles12_xen > sles12_xen.xml
  2. Verify all disk image paths are correct from the KVM host's perspective. This is not a problem when converting on one machine, but may require manual changes when converting using an XML dump from another host.

    <source file='/var/lib/libvirt/images/XenPool/SLES.qcow2'/>
    Tip
    Tip: Copying Images

    To avoid copying an image twice, manually copy the disk image(s) directly to the libvirt storage pool. Update the source file entries in the XML description file. The virt-v2v process will detect the existing disks and convert them in place.

  3. Run virt-v2v to convert to KVM virtual machine:

    root # virt-v2v sles12_xen.xml1 \
    -i LIBVIRTXML2 \
    -os remote_host.example.com:/exported_dir3 \
    --bridge br04 \
    -on sles12_kvm5

    1

    The XML description of the source Xen-based virtual machine.

    2

    virt-v2v will read the information about the source virtual machine form a libvirt XML file.

    3

    Storage pool where the target virtual machine disk image will be placed. In this example, the image will be placed on an NFS share /exported_dir on the remote_host.example.com server.

    4

    The target KVM-based virtual machine will use the network bridge br0 on the host.

    5

    The target virtual machine will be renamed to sles12_kvm to prevent name collision with the existing virtual machine of the same name.

1.4.2 Conversion Based on the libvirt Domain Name

This method is useful if you are still running libvirt under Xen, and plan to reboot to the KVM hypervisor later.

  1. Find the libvirt domain name of the virtual machine you want to convert.

    root # virsh list
     Id    Name                           State
    ----------------------------------------------------
    [...]
      2     sles12_xen                     running
    [...]

    sles12_xen is the source virtual machine to convert.

  2. Run virt-v2v to convert to KVM virtual machine:

    root # virt-v2v sles12_xen1 \
    -i libvirt2 \
    -os storage_pool3 \
    --network eth04 \
    -of qcow25 \
    -oa sparce6 \
    -on sles12_kvm

    1

    The domain name of the Xen-based virtual machine.

    2

    virt-v2v will read the information about the source virtual machine directly from the active libvirt connection.

    3

    The target disk image will be placed in a local libvirt storage pool.

    4

    All guest bridges (or networks) will be connected to a locally managed network.

    5

    Format for the disk image of the target virtual machine. Supported options are raw or qcow2.

    6

    If the converted guest disk space will be sparse or preallocated.

1.4.3 Converting a Remote Xen Virtual Machine

This method is useful if you need to convert a Xen virtual machine running on a remote host. As virt-v2v connects to the remote host via ssh, ensure that SSH service is running on the host.

Note
Note: Passwordless SSH Access

Starting with SLES 12 SP2, virt-v2v requires a passwordless SSH connection to the remote host. This means a connection using an SSH key added to the ssh-agent. See man ssh-keygen and man ssh-add for more details on this.

To connect to a remote libvirt connection, construct a valid connection URI relevant for your remote host. In the following example, the remote host name is remote_host.example.com, and the user name for the connection is root. The connection URI then looks as follows:

xen+ssh://root@remote_host.example.com/

For more information on libvirt connection URIs, see http://libvirt.org/uri.html.

  1. Find the libvirt domain name of the remote virtual machine you want to convert.

    root # virsh -c xen+ssh://root@remote_host.example.com/ list
     Id    Name                           State
    ----------------------------------------------------
      1     sles12_xen                     running
    [...]

    sles12_xen is the source virtual machine to convert.

  2. The virt-v2v command for the remote connection looks like this:

    root # virt-v2v sles12_xen \
    -i libvirt \
    -ic xen+ssh://root@remote_host.example.com/ \
    -os local_storage_pool \
    --bridge br0

1.5 Running Converted Virtual Machines

After virt-v2v completes successfully, a new libvirt domain will be created with the name specified with the -on option. If you did not specify -on, the same name as the source virtual machine will be used. The new guest can be managed with standard libvirt tools, such as virsh or Virtual Machine Manager.

Tip
Tip: Rebooting the Machine

If you completed the conversion under Xen as described in Section 1.4.2, “Conversion Based on the libvirt Domain Name”, you may need to reboot the host machine and boot with the non-Xen kernel.

2 Xen to KVM Manual Migration

2.1 General Outline

The preferred solution to manage virtual machines is based on libvirt; for more information, see http://libvirt.org/. It has several advantages over the manual way of defining and running virtual machines—libvirt is cross-platform, supports many hypervisors, has secure remote management, has virtual networking, and, most of all, provides a unified abstract layer to manage virtual machines. Therefore the main focus of this article is on the libvirt solution.

Generally, the Xen to KVM migration runs in the following basic steps:

  1. Make a backup copy of the original Xen VM Guest.

  2. OPTIONAL: Apply changes specific to paravirtualized guests.

  3. Obtain information about the original Xen VM Guest and update it to KVM equivalents.

  4. Shut down the guest on the Xen host, and run the new one under the KVM hypervisor.

Warning
Warning: No Live Migration

The Xen to KVM migration cannot be done live while the source VM Guest is running. Before running the new KVM-ready VM Guest, you are advised to shut down the original Xen VM Guest.

2.2 Back Up the Xen VM Guest

To back up your Xen VM Guest, follow these steps:

  1. Identify the relevant Xen guest you want to migrate, and remember its ID/name.

    # virsh list --all
    Id Name                 State
    ----------------------------------
     0 Domain-0             running
     1 SLES11SP3            running
    [...]
  2. Shut down the guest. You can do this either by shutting down the guest OS, or with virsh:

    # virsh shutdown SLES11SP3
  3. Backup its configuration to an XML file.

    # virsh dumpxml SLES11SP3 > sles11sp3.xml
  4. Backup its disk image file. Use the cp or rsync commands to create the backup copy. Remember that it is always a good idea to check the copy with the md5sum command.

  5. After the image file is backed up, you can start the guest again with

    # virsh start SLES11SP3

2.3 Changes Specific to Paravirtualized Guests

Apply the following changes if you are migrating a paravirtualized Xen guest. You can do it either on the running guest, or on the stopped guest using guestfs-tools.

Important
Important

After applying the changes described in this section, the image file related to the migrated VM Guest will not be usable under Xen anymore.

2.3.1 Install the Default Kernel

Warning
Warning: No Booting

After you installed the default kernel, do not try to boot the Xen guest with it, the system will not boot.

Before cloning the Xen guest disk image for use under the KVM hypervisor, make sure it is bootable without the Xen hypervisor. This is very important for paravirtualized Xen guests as they usually contain a special Xen kernel, and often do not have a complete GRUB 2 boot loader installed.

  1. For SLES 11 update the /etc/sysconfig/kernel file. Change the INITRD_MODULES parameter by removing all Xen drivers and replacing the with virtio drivers. Replace

    INITRD_MODULES="xenblk xennet"

    with

    INITRD_MODULES="virtio_blk virtio_pci virtio_net virtio_balloon"

    For SLES 12 search for xenblk xennet in /etc/dracut.conf.d/*.conf and replace them with virtio_blk virtio_pci virtio_net virtio_balloon

  2. Paravirtualized Xen guests are running a specific Xen kernel. To run the guest under KVM, you need to install the default kernel.

    Note
    Note: Default Kernel Is Already Installed

    You do not need to install the default kernel for a fully virtualized guests as it is already installed.

    Enter rpm -q kernel-default on the Xen guest to find out if the default kernel is installed. If not, install it with zypper in kernel-default.

    The kernel we are going to use to boot the guest under KVM must have virtio (paravirtualized) drivers available. Run the following command to find out. Do not forget to replace 3.8.9-4 with your kernel version:

    # find /lib/modules/3.8.9-4-default/kernel/drivers/ -name virtio*
    /lib/modules/3.8.9-4-default/kernel/drivers/net/virtio_net.ko
    /lib/modules/3.8.9-4-default/kernel/drivers/scsi/virtio_scsi.ko
    /lib/modules/3.8.9-4-default/kernel/drivers/block/virtio_blk.ko
    /lib/modules/3.8.9-4-default/kernel/drivers/char/virtio_console.ko
    /lib/modules/3.8.9-4-default/kernel/drivers/char/hw_random/virtio-rng.ko
    /lib/modules/3.8.9-4-default/kernel/drivers/virtio
    /lib/modules/3.8.9-4-default/kernel/drivers/virtio/virtio.ko
    /lib/modules/3.8.9-4-default/kernel/drivers/virtio/virtio_pci.ko
    /lib/modules/3.8.9-4-default/kernel/drivers/virtio/virtio_balloon.ko
    /lib/modules/3.8.9-4-default/kernel/drivers/virtio/virtio_ring.ko
    /lib/modules/3.8.9-4-default/kernel/drivers/virtio/virtio_mmio.ko
  3. Update /etc/fstab. Change any storage devices from xvda to vda.

  4. Update the boot loader configuration. Enter rpm -q grub2 on the Xen guest to find out if GRUB 2 is already installed. If not, install it with zypper in grub2.

    Now make the newly installed default kernel the default for booting the OS. Also remove/update the kernel command line options that may refer to Xen-specific devices. You can do it either with YaST (System › Boot Loader), or manually:

    • Find the preferred Linux boot menu entry by listing them all:

      cat /boot/grub2/grub.cfg | grep 'menuentry '

      Remember the order number (counted from zero) of the one you newly installed.

    • Set it the default boot menu entry:

      grub2-set-default N

      Replace N with the number of the boot menu entry you previously discovered.

    • Open /etc/default/grubfor editing, and look for GRUB_CMDLINE_LINUX_DEFAULT and GRUB_CMDLINE_LINUX_RECOVERY options. Remove/update any reference to Xen-specific devices. In the following example, you can replace

      root=/dev/xvda1 disk=/dev/xvda console=xvc

      with

      root=/dev/vda1 disk=/dev/vda

      Note that you need to remove all references to xvc-type consoles (such as xvc0).

  5. Update device.map in one of /boot/grub2 or /boot/grub2-efi directories. Change any storage device from xvda to vda.

  6. To import new default settings, run

    grub2-mkconfig -o /boot/grub2/grub.cfg

2.3.2 Update the Guest for Boot under KVM

  1. Update the system to use default serial console. List the configured consoles, and remove symbolic links to xvc? ones.

    # ls -l /etc/systemd/system/getty.target.wants/
    getty@tty1.service -> /usr/lib/systemd/system/getty@.service
    getty@xvc0.service -> /usr/lib/systemd/system/getty@xvc0.service
    getty@xvc1.service -> /usr/lib/systemd/system/getty@xvc1.service
    
    # rm /etc/systemd/system/getty.target.wants/getty@xvc?.service
  2. Update the /etc/securetty file. Replace xvc0 with ttyS0.

2.4 Update the Xen VM Guest Configuration

This section describes how to export the configuration of the original Xen VM Guest, and what particular changes to apply to it so it can be imported as a KVM guest into libvirt.

2.4.1 Export the Xen VM Guest Configuration

First export the configuration of the guest and save it to a file. A typical one may look like this:

# virsh dumpxml SLES11SP3
<domain type='xen'>
  <name>SLES11SP3</name>
  <uuid>fa9ea4d7-8f95-30c0-bce9-9e58ffcabeb2</uuid>
  <memory>524288</memory>
  <currentMemory>524288</currentMemory>
  <vcpu>1</vcpu>
  <bootloader>/usr/bin/pygrub</bootloader>
  <os>
    <type>linux</type>
  </os>
  <clock offset='utc'/>
  <on_poweroff>destroy</on_poweroff>
  <on_reboot>restart</on_reboot>
  <on_crash>restart</on_crash>
  <devices>
    <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
    <disk type='file' device='disk'>
      <driver name='file'/>
      <source file='/var/lib/libvirt/images/SLES_11_SP2_JeOS.x86_64-0.0.2_para.raw'/>
      <target dev='xvda' bus='xen'/>
    </disk>
    <interface type='bridge'>
      <mac address='00:16:3e:2d:91:c3'/>
      <source bridge='br0'/>
      <script path='vif-bridge'/>
    </interface>
    <console type='pty'>
      <target type='xen' port='0'/>
    </console>
    <input type='mouse' bus='xen'/>
    <graphics type='vnc' port='-1' autoport='yes' keymap='en-us'/>
  </devices>
</domain>

You can find detailed information on the libvirt XML format for VM Guest description at http://libvirt.org/formatdomain.html.

2.4.2 General Changes to the Guest Configuration

You need to make a few general changes to the exported Xen guest XML configuration to run it under the KVM hypervisor. The following applies to both fully virtualized and paravirtualized guests. Note that not all of the following XML elements need to be in your specific configuration.

Tip
Tip: Conventions Used

To refer to a node in the XML configuration file, an XPath syntax will be used throughout this document. For example, to refer to a <name> inside the <domain> tag

<domain>
  <name>sles11sp3</name>
</domain>

an XPath equivalent /domain/name will be used.

  1. Change the type attribute of the /domain element from xento kvm.

  2. Remove the /domain/bootloader element section.

  3. Remove the /domain/bootloader_args element section.

  4. Change the /domain/os/type element value from linux to hvm.

  5. Add <boot dev="hd"/> under the /domain/os element.

  6. Add the arch attribute to the /domain/os/type element. Acceptable values are arch=”x86_64” or arch=”i686”

  7. Change the /domain/devices/emulator element from /usr/lib/xen/bin/qemu-dm' to /usr/bin/qemu-kvm.

  8. For each disk associated with the paravirtualized (PV) guest, change the following:

    • Change the name attribute of the /domain/devices/disk/driver element from file to qemu, and add a type attribute for the disk type. For example, valid options include raw or qcow2.

    • Change the dev attribute of the /domain/devices/disk/target element from xvda to vda.

    • Change the bus attribute of the /domain/devices/disk/target element from xen to virtio.

  9. For each network interface card, do the following changes:

    • If there is model defined in /domain/devices/interface, change its type attribute value to virtio

      <model type=”virtio”>
    • Delete all /domain/devices/interface/script sections.

    • Delete all /domain/devices/interface/target elements if the dev attribute starts with vif or vnet or veth. If using a custom network then change the dev value to that target.

  10. Remove the /domain/devices/console element section if it exists.

  11. Remove the /domain/devices/serial element section if it exists.

  12. Change the bus attribute on the /domain/devices/input element from xen to ps2.

  13. Add the following element for memory ballooning features under the /domain/devices element.

    <memballoon model="virtio"/>
Tip
Tip: Device Name

<target dev='hda' bus='ide'/> controls the device under which the disk is exposed to the guest OS. The dev attribute indicates the "logical" device name. The actual device name specified is not guaranteed to map to the device name in the guest OS. Therefore you may need to change the disk mapping on the boot loader command line. For example, if the boot loader expects a root disk to be hda2 but KVM still sees it as sda2, change the boot loader command line from

[...] root=/dev/hda2 resume=/dev/hda1 [...]

to

[...] root=/dev/sda2 resume=/dev/sda1 [...]

In the case of paravirtualized xvda devices, change it to

[...] root=/dev/vda2 resume=/dev/vda1 [...]

Otherwise the VM Guest will refuse to boot in the KVM environment.

2.4.3 The Target KVM Guest Configuration

After having applied all the modifications mentioned above, you end up with the following configuration for your KVM guest:

<domain type='kvm'>
  <name>SLES11SP3</name>
  <uuid>fa9ea4d7-8f95-30c0-bce9-9e58ffcabeb2</uuid>
  <memory>524288</memory>
  <currentMemory>524288</currentMemory>
  <vcpu cpuset='0-3'>1</vcpu>
  <os>
    <type arch=”x86_64”>hvm</type>
    <boot dev="hd"/>
  </os>
  <clock offset='utc'/>
  <on_poweroff>destroy</on_poweroff>
  <on_reboot>restart</on_reboot>
  <on_crash>restart</on_crash>
  <devices>
    <emulator>/usr/bin/qemu-kvm</emulator>
    <disk type='file' device='disk'>
      <driver name='qemu' type="raw"/>
      <source file='/var/lib/libvirt/images/SLES_11_SP2_JeOS.x86_64-0.0.2_para.raw'/>
      <target dev='vda' bus='virtio'/>
    </disk>
    <interface type='bridge'>
      <mac address='00:16:3e:2d:91:c3'/>
      <source bridge='br0'/>
    </interface>
    <input type='mouse' bus='usb'/>
    <graphics type='vnc' port='5900' autoport='yes' keymap='en-us'/>
    <memballoon model="virtio"/>
  </devices>
</domain>

Save the configuration to a file in your home directory. After you later import it, it will be copied to the default /etc/libvirt/qemu. Suppose you save the file as SLES11SP3.xml.

2.5 Migrate the VM Guest

After you updated the VM Guest configuration, and applied necessary changes to the guest OS, shut down the original Xen guest, and run its clone under the KVM hypervisor.

  1. Shut down the guest on the Xen host by running shutdown -h now as root from the console.

  2. Copy the disk files associated with the VM Guest if needed. A default configuration will require the Xen disk files to be copied from /var/lib/xen/images to /var/lib/kvm/images. The /var/lib/kvm/images directory may need to be created (as root) if you have not previously created a VM Guest.

  3. Create the new domain, and register it with libvirt:

    # virsh define SLES11SP3.xml
     Domain SLES11SP3 defined from SLES11SP3.xml
  4. Verify that the new guest is seen in the KVM configuration:

    virsh list –all
  5. After the domain is created, you can start it:

    # virsh start SLES11SP3
     Domain SLES11SP3 started

3 For More Information

For more information on libvirt, see http://libvirt.org.

You can find more details on libvirt XML format at http://libvirt.org/formatdomain.html.

For more information on virtualization with Xen and KVM, see the SUSE Linux Enterprise Server documentation at http://www.suse.com/doc/.

4 Documentation Updates

This section lists content changes for this document.

4.1 October 2016 (Release of SUSE Linux Enterprise Server 12 SP2)

5 Legal Notice

  • Filename: common_copyright_quick.xml
  • ID: no ID found

Copyright© 2006– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see http://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors, nor the translators shall be held liable for possible errors or the consequences thereof.

SUSE Linux Enterprise Server 12 SP3

Virtualization Best Practices

SUSE Linux Enterprise Server 12 SP3

Publication Date: April 04, 2018

1 Virtualization Scenarios

Virtualization offers a lot of capabilities to your environment. It can be used in multiple scenarios. To get more details about Virtualization Capabilities and Virtualization Benefits, refer to the Virtualization Guide.

This best practice guide will provide advice for making the right choice in your environment. It will recommend or discourage the usage of options depending on your workload. Fixing configuration issues and performing tuning tasks will increase the performance of VM Guest's near to bare metal.

2 Before You Apply Modifications

2.1 Back Up First

Changing the configuration of the VM Guest or the VM Host Server can lead to data loss or an unstable state. It is really important that you do backups of files, data, images, etc. before making any changes. Without backups you cannot restore the original state after a data loss or a misconfiguration. Do not perform tests or experiments on production systems.

2.2 Test Your Workloads

The efficiency of a virtualization environment depends on many factors. This guide provides a reference for helping to make good choices when configuring virtualization in a production environment. Nothing is carved in stone. Hardware, workloads, resource capacity, etc. should all be considered when planning, testing, and deploying your virtualization infra-structure. Testing your virtualized workloads is vital to a successful virtualization implementation.

3 Recommendations

3.1 Prefer the libvirt Framework

SUSE strongly recommends using the libvirt framework to configure, manage, and operate VM Host Servers, containers and VM Guest. It offers a single interface (GUI and shell) for all supported virtualization technologies and therefore is easier to use than the hypervisor-specific tools.

We do not recommend using libvirt and hypervisor-specific tools at the same time, because changes done with the hypervisor-specific tools may not be recognized by the libvirt tool set. See https://www.suse.com/documentation/sles-12/book_virt/data/cha_libvirt_overview.html for more information on libvirt.

3.2 qemu-system-i386 Compared to qemu-system-x86_64

Similar to real 64-bit PC hardware, qemu-system-x86_64 supports VM Guests running a 32-bit or a 64-bit operating system. Because qemu-system-x86_64 usually also provides better performance for 32-bit guests, SUSE generally recommends using qemu-system-x86_64 for both 32-bit and 64-bit VM Guests on KVM. Scenarios where qemu-system-i386 is known to perform better are not supported by SUSE.

Xen also uses binaries from the qemu package but prefers qemu-system-i386, which can be used for both 32-bit and 64-bit Xen VM Guests. To maintain compatibility with the upstream Xen Community, SUSE encourages using qemu-system-i386 for Xen VM Guests.

4 VM Host Server Configuration and Resource Allocation

Allocation of resources for VM Guests is a crucial point when administrating virtual machines. When assigning resources to VM Guests, be aware that overcommitting resources may affect the performance of the VM Host Server and the VM Guests. If all VM Guests request all their resources simultaneously, the host needs to be able to provide all of them. If not, the host's performance will be negatively affected and this will in turn also have negative effects on the VM Guest's performance.

4.1 Memory

Linux manages memory in units called pages. On most systems the default page size is 4 KB. Linux and the CPU need to know which pages belong to which process. That information is stored in a page table. If a lot of processes are running, it takes more time to find where the memory is mapped, because of the time required to search the page table. To speed up the search, the TLB (Translation Lookaside Buffer) was invented. But on a system with a lot of memory, the TLB is not enough. To avoid any fallback to normal page table (resulting in a cache miss, which is time consuming), huge pages can be used. Using huge pages will reduce TLB overhead and TLB misses (pagewalk). A host with 32 GB (32*1014*1024 = 33,554,432 KB) of memory and a 4 KB page size has a TLB with 33,554,432/4 = 8,388,608 entries. Using a 2 MB (2048 KB) page size, the TLB only has 33554432/2048 = 16384 entries, considerably reducing TLB misses.

4.1.1 Configuring the VM Host Server and the VM Guest to use Huge Pages

Current CPU architectures support larger pages than 4 KB: huge pages. To determine the size of huge pages available on your system (could be 2 MB or 1 GB), check the flags line in the output of /proc/cpuinfo for occurrences of pse and/or pdpe1gb.

Table 1: Determine the Available Huge Pages Size

CPU flag

Huge pages size available

Empty string

No huge pages available

pse

2 MB

pdpe1gb

1 GB

Using huge pages improves performance of VM Guests and reduces host memory consumption.

By default the system uses THP. To make huge pages available on your system, activate it at boot time with hugepages=1, and—optionally—add the huge pages size with, for example, hugepagesz=2MB.

Note
Note: 1 GB huge pages

1 GB pages can only be allocated at boot time and cannot be freed afterward.

To allocate and use the huge page table (HugeTlbPage) you need to mount hugetlbfs with correct permissions.

Note
Note: Restrictions of Huge Pages

Even if huge pages provide the best performance, they do come with some drawbacks. You lose features such as Memory ballooning (see Section 6.1.3, “virtio balloon”), KSM (see Section 4.1.4, “KSM and Page Sharing”), and huge pages cannot be swapped.

Procedure 2: Configuring the use of huge pages
  1. Mount hugetlbfs to /dev/hugepages:

    tux > sudo mount -t hugetlbfs hugetlbfs /dev/hugepages
  2. To reserve memory for huge pages use the sysctl command. If your system has a huge page size of 2 MB (2048 KB), and you want to reserve 1 GB (1,048,576 KB) for your VM Guest, you need 1,048,576/2048=512 pages in the pool:

    tux > sudo sysctl vm.nr_hugepages=512

    The value is written to /proc/sys/vm/nr_hugepages and represents the current number of persistent huge pages in the kernel's huge page pool. Persistent huge pages will be returned to the huge page pool when freed by a task.

  3. Add the memoryBacking element in the VM Guest configuration file (by running virsh edit CONFIGURATION).

    <memoryBacking>
      <hugepages/>
    </memoryBacking>
  4. Start your VM Guest and check on the host whether it uses hugepages:

    tux > cat /proc/meminfo | grep HugePages_
    HugePages_Total:1     512
    HugePages_Free:2       92
    HugePages_Rsvd:3        0
    HugePages_Surp:4        0

    1

    Size of the pool of huge pages

    2

    Number of huge pages in the pool that are not yet allocated

    3

    Number of huge pages for which a commitment to allocate from the pool has been made, but no allocation has yet been made

    4

    Number of huge pages in the pool above the value in /proc/sys/vm/nr_hugepages. The maximum number of surplus huge pages is controlled by /proc/sys/vm/nr_overcommit_hugepages

4.1.2 Transparent Huge Pages

Transparent huge pages (THP) provide a way to dynamically allocate huge pages with the khugepaged kernel thread, rather than manually managing their allocation and use. Workloads with contiguous memory access patterns can benefit greatly from THP. A 1000 fold decrease in page faults can be observed when running synthetic workloads with contiguous memory access patterns. Conversely, workloads with sparse memory access patterns (like databases) may perform poorly with THP. In such cases it may be preferable to disable THP by adding the kernel parameter transparent_hugepage=never, rebuild your grub2 configuration, and reboot. Verify if THP is disabled with:

tux > cat /sys/kernel/mm/transparent_hugepage/enabled
always madvise [never]

If disabled, the value never is shown in square brackets like in the example above.

Note
Note: Xen

THP is not available under Xen.

4.1.3 Xen-specific Memory Notes

4.1.3.1 Managing Domain-0 Memory

When using the Xen hypervisor, by default a small percentage of system memory is reserved for the hypervisor. All remaining memory is automatically allocated to Domain-0. When virtual machines are created, memory is ballooned out of Domain-0 to provide memory for the virtual machine. This process is called "autoballooning".

Autoballooning has several limitations:

  • Reduced performance while dom0 is ballooning down to free memory for the new domain.

  • Memory freed by ballooning is not confined to a specific NUMA node. This can result in performance problems in the new domain because of using a non-optimal NUMA configuration.

  • Failure to start large domains because of delays while ballooning large amounts of memory from dom0.

For these reasons, we strongly recommend to disable autoballooning and give Domain-0 the memory needed for its workload. Determining Domain-0 memory and vCPU sizing should follow a similar process as any other virtual machine.

Autoballooning is controlled by the toolstack used to manage your Xen installation. For the xl/libxl toolstack, autoballooning is controlled by the autoballoon setting in /etc/xen/xl.conf. For the libvirt+libxl toolstack, autoballooning is controlled by the autoballoon setting in /etc/libvirt/libxl.conf.

The amount of memory initially allocated to Domain-0 is controlled by the Xen hypervisor dom0_mem parameter. For example, to set the initial memory allocation of Domain-0 to 8GB, add dom0_mem=8G to the Xen hypervisor parameters. The dom0_mem parameter can also be used to specify the minimum and maximum memory allocations for Domain-0. For example, to set the initial memory of Domain-0 to 8GB, but allow it to be changed (ballooned) anywhere between 4GB and 16GB, add the following to the Xen hypervisor parameters: dom0_mem=8G,min:4G,max:8G.

  • To set dom0_mem on SLE 11 products, modify /boot/grub/menu.lst, adding dom0_mem=XX to the Xen hypervisor (xen.gz) parameters. The change will be applied at next reboot.

  • To set dom0_mem on SLE 12 products, modify /etc/default/grub, adding dom0_mem=XX to GRUB_CMDLINE_XEN_DEFAULT. See Section 7.5, “Change Kernel Parameters at Boot Time” for more information.

Autoballooning is enabled by default since it is extremely difficult to determine a predefined amount of memory required by Domain-0. Memory needed by Domain-0 is heavily dependent on the number of hosted virtual machines and their configuration. Users must ensure Domain-0 has sufficient memory resources to accommodate virtual machine workloads.

4.1.3.2 xenstore in tmpfs

When using Xen, we recommend to place the xenstore database on tmpfs. xenstore is used as a control plane by the xm/xend and xl/libxl toolstacks and the front-end and back-end drivers servicing domain I/O devices. The load on xenstore increases linearly as the number of running domains increase. If you anticipate hosting many VM Guest on a Xen host, move the xenstore database onto tmpfs to improve overall performance of the control plane. Mount the /var/lib/xenstored directory on tmpfs:

tux > sudo mount -t tmpfs tmpfs /var/lib/xenstored/

4.1.4 KSM and Page Sharing

Kernel Samepage Merging is a kernel feature that allows for lesser memory consumption on the VM Host Server by sharing data VM Guests have in common. The KSM daemon ksmd periodically scans user memory looking for pages of identical content which can be replaced by a single write-protected page. To enable KSM, run:

tux > sudo echo 1 > /sys/kernel/mm/ksm/run

One advantage of using KSM from a VM Guest's perspective is that all guest memory is backed by host anonymous memory. You can share pagecache, tmpfs or any kind of memory allocated in the guest.

KSM is controlled by sysfs. You can check KSM's values in /sys/kernel/mm/ksm/:

  • pages_shared: The number of shared pages that are being used (read-only).

  • pages_sharing: The number of sites sharing the pages (read-only).

  • pages_unshared: The number of pages that are unique and repeatedly checked for merging (read-only).

  • pages_volatile: The number of pages that are changing too fast to be considered for merging (read-only).

  • full_scans: The number of times all mergeable areas have been scanned (read-only).

  • sleep_millisecs: The number of milliseconds ksmd should sleep before the next scan. A low value will overuse the CPU, consuming CPU time that could be used for other tasks. We recommend a value greater than 1000.

  • pages_to_scan: The number of present pages to scan before ksmd goes to sleep. A high value will overuse the CPU. We recommend to start with a value of 1000, and then adjust as necessary based on the KSM results observed while testing your deployment.

  • merge_across_nodes: By default the system merges pages across NUMA nodes. Set this option to 0 to disable this behavior.

Note
Note: Use Cases

KSM is a good technique to over-commit host memory when running multiple instances of the same application or VM Guest. When applications and VM Guest are heterogeneous and do not share any common data, it is preferable to disable KSM. In a mixed heterogeneous and homogeneous environment, KSM can be enabled on the host but disabled on a per VM Guest basis. Use virsh edit to disable page sharing of a VM Guest by adding the following to the guest's XML configuration:

<memoryBacking>
   <nosharepages/>
</memoryBacking>
Warning
Warning: Avoid Out-of-Memory Conditions

KSM can free up some memory on the host system, but the administrator should reserve enough swap to avoid out-of-memory conditions if that shareable memory decreases. If the amount of shareable memory decreases, the use of physical memory is increased.

Warning
Warning: Memory Access Latencies

By default, KSM will merge common pages across NUMA nodes. If the merged, common page is now located on a distant NUMA node (relative to the node running the VM Guest vCPUs), this may degrade VM Guest performance. If increased memory access latencies are noticed in the VM Guest, disable cross-node merging with the merge_across_nodes sysfs control:

tux > sudo echo 0 > /sys/kernel/mm/ksm/merge_across_nodes

4.1.5 VM Guest: Memory Hotplug

To optimize the usage of your host memory, it may be useful to hotplug more memory for a running VM Guest when required. To support memory hotplugging, you must first configure the <maxMemory> tag in the VM Guest's configuration file:

<maxMemory1 slots='16'2 unit='KiB'>209715203</maxMemory>
  <memory4 unit='KiB'>1048576</memory>
<currentMemory5 unit='KiB'>1048576</currentMemory>

1

Runtime maximum memory allocation of the guest.

2

Number of slots available for adding memory to the guest

3

Valid units are:

  • "KB" for kilobytes (1,000 bytes)

  • "k" or "KiB" for kibibytes (1,024 bytes)

  • "MB" for megabytes (1,000,000 bytes)

  • "M" or "MiB" for mebibytes (1,048,576 bytes)

  • "GB" for gigabytes (1,000,000,000 bytes)

  • "G" or "GiB" for gibibytes (1,073,741,824 bytes)

  • "TB" for terabytes (1,000,000,000,000 bytes)

  • "T" or "TiB" for tebibytes (1,099,511,627,776 bytes)

4

Maximum allocation of memory for the guest at boot time

5

Actual allocation of memory for the guest

To hotplug memory devices into the slots, create a file mem-dev.xml like the following:

<memory model='dimm'>
  <target>
  <size unit='KiB'>524287</size>
  <node>0</node>
  </target>
</memory>

And attach it with the following command:

tux > virsh attach-device vm-name mem-dev.xml

For memory device hotplug, the guest must have at least 1 NUMA cell defined (see Section 4.6.3.1, “VM Guest Virtual NUMA Topology”).

4.2 Swap

Swap is usually used by the system to store underused physical memory (low usage, or not accessed for a long time). To prevent the system running out of memory, setting up a minimum swap is highly recommended.

4.2.1 swappiness

The swappiness setting controls your system's swap behavior. It defines how memory pages are swapped to disk. A high value of swappiness results in a system that swaps more often. Available values range from 0 to 100. A value of 100 tells the system to find inactive pages and put them in swap. A value of 0 disables swapping.

To do some testing on a live system, change the value of /proc/sys/vm/swappiness on the fly and check the memory usage afterward:

tux > sudo echo 35 > /proc/sys/vm/swappiness
tux > free -h
total       used       free     shared    buffers     cached
Mem:      24616680    4991492   19625188     167056     144340    2152408
-/+ buffers/cache:    2694744   21921936
Swap:      6171644          0    6171644

To permanently set a swappiness value, add a line in /etc/systcl.conf, for example:

vm.swappiness = 35

You can also control the swap by using the swap_hard_limit element in the XML configuration of your VM Guest. Before setting this parameter and using it in a production environment, do some testing because the host can terminate the domain if the value is too low.

<memtune>1
  <hard_limit unit='G'>1</hard_limit>2
  <soft_limit unit='M'>128</soft_limit>3
  <swap_hard_limit unit='G'>2</swap_hard_limit>4
</memtune>

1

This element provides memory tunable parameters for the domain. If this is omitted, it defaults to the defaults provided b the operating system.

2

Maximum memory the guest can use. To avoid any problems on the VM Guest it is strongly recommended not to use this parameter.

3

The memory limit to enforce during memory contention.

4

The maximum memory plus swap the VM Guest can use.

4.3 I/O

4.3.1 I/O Scheduler

The default I/O scheduler is Completely Fair Queuing (CFQ). The main aim of the CFQ scheduler is to provide a fair allocation of the disk I/O bandwidth for all processes that request an I/O operation. You can have different I/O schedulers for different devices.

To get better performance in host and VM Guest, use noop in the VM Guest (disable the I/O scheduler) and the deadline scheduler for a virtualization host.

Procedure 3: Checking and Changing the I/O Scheduler at Runtime
  1. To check your current I/O scheduler for your disk (replace sdX by the disk you want to check), run:

    tux > cat /sys/block/sdX/queue/scheduler
    noop deadline [cfq]

    The value in square brackets is the one currently selected (cfq in the example above).

  2. You can change the scheduler at runtime with the following command:

    tux > sudo echo deadline > /sys/block/sdX/queue/scheduler

To permanently set an I/O scheduler for all disks of a system, use the kernel parameter elevator. The respective values are elevator=deadline for the VM Host Server and elevator=noop for VM Guests. See Section 7.5, “Change Kernel Parameters at Boot Time” for further instructions.

If you need to specify different I/O schedulers for each disk, create the file /usr/lib/tmpfiles.d/IO_ioscheduler.conf with a content similar to the following example. It defines the deadline scheduler for /dev/sda and the noop scheduler for /dev/sdb. This feature is available on SLE 12 only.

w /sys/block/sda/queue/scheduler - - - - deadline
w /sys/block/sdb/queue/scheduler - - - - noop

4.3.2 Asynchronous I/O

Many of the virtual disk backends use Linux Asynchronous I/O (aio) in their implementation. By default, the maximum number aio contexts is set to 65536, which can be exceeded when running hundreds of VM Guests using virtual disks serviced by Linux Asynchronous I/O. When running large numbers of VM Guests on a VM Host Server, consider increasing /proc/sys/fs/aio-max-nr.

Procedure 4: Checking and Changing aio-max-nr at Runtime
  1. To check your current aio-max-nr setting run:

    tux > cat /proc/sys/fs/aio-max-nr
    65536
  2. You can change aio-max-nr at runtime with the following command:

    tux > sudo echo 131072 > /proc/sys/fs/aio-max-nr

To permanently set aio-max-nr, add an entry to a local sysctl file. For example, append the following to /etc/sysctl.d/99-sysctl.conf:

fs.aio-max-nr = 1048576

4.3.3 I/O Virtualization

SUSE products support various I/O virtualization technologies. The following table lists advantages and disadvantages of each technology. For more information about I/O in virtualization refer to the I/O in Virtualization chapter in the SUSE Linux Enterprise Server 12 SP3 Virtualization Guide.

Table 2: I/O Virtualization Solutions

Technology

Advantage

Disadvantage

Device Assignment (pass-through)

Device accessed directly by the guest

No sharing among multiple guests

High performance

Live migration is complex

PCI device limit is 8 per guest

Limited number of slots on a server

Full virtualization (IDE, SATA, SCSI, e1000)

VM Guest compatibility

Bad performance

Easy for live migration

Emulated operation

Para-virtualization (virtio-blk, virtio-net, virtio-scsi)

Good performance

Modified guest (PV drivers)

Easy for live migration

Efficient host communication with VM Guest

4.4 Storage and File System

Storage space for VM Guests can either be a block device (for example, a partition on a physical disk), or an image file on the file system:

Table 3: Block Devices Compared to Disk Images

Technology

Advantages

Disadvantages

Block devices

  • Better performance

  • Use standard tools for administration/disk modification

  • Accessible from host (pro and con)

  • Live migration is complex

  • Impossible to increase capacity

Image files

  • Easier system management

  • Easily move, clone, expand, back up domains

  • Comprehensive toolkit (guestfs) for image manipulation

  • Reduce overhead through sparse files

  • Fully allocate for best performance

  • Lower performance than block devices

For detailed information about image formats and maintaining images refer to Section 5, “VM Guest Images”.

If your image is stored on an NFS share, you should check some server and client parameters to improve access to the VM Guest image.

4.4.1 NFS Read/Write (Client)

Options rsize and wsize specify the size of the chunks of data that the client and server pass back and forth to each other. You should ensure NFS read/write sizes are sufficiently large, especially for large I/O. Change the rsize and wsize parameter in your /etc/fstab by increasing the value to 16 KB. This will ensure that all operations can be frozen if there is any instance of hanging.

nfs_server:/exported/vm_images1 /mnt/images2 nfs3 rw4,hard5,sync6, rsize=81927,wsize=81928 0 0

1

NFS server's host name and export path name.

2

Where to mount the NFS exported share.

3

This is an nfs mount point.

4

This mount point will be accessible in read/write.

5

Determines the recovery behavior of the NFS client after an NFS request times out. hard is the best option to avoid data corruption.

6

Any system call that writes data to files on that mount point causes that data to be flushed to the server before the system call returns control to user space.

7

Maximum number of bytes in each network READ request that the NFS client can receive when reading data from a file on an NFS server.

8

Maximum number of bytes per network WRITE request that the NFS client can send when writing data to a file on an NFS server.

4.4.2 NFS Threads (Server)

Your NFS server should have enough NFS threads to handle multi-threaded workloads. Use the nfsstat tool to get some RPC statistics on your server:

tux > sudo nfsstat -rc
Client rpc stats:
calls      retrans    authrefrsh
6401066    198          0          0

If the retrans is equal to 0, everything is fine. Otherwise, the client needs to retransmit, so increase the USE_KERNEL_NFSD_NUMBER variable in /etc/sysconfig/nfs, and adjust accordingly until retrans is equal to 0.

4.5 CPUs

Host CPU components will be translated to virtual CPUs in a VM Guest when being assigned. These components can either be:

  • CPU processor: this describes the main CPU unit, which usually has multiple cores and may support Hyper-Threading.

  • CPU core: a main CPU unit can provide more than one core, and the proximity of cores speeds up the computation process and reduces energy costs.

  • CPU Hyper-Threading: this implementation is used to improve parallelization of computations, but this is not as efficient as a dedicated core.

4.5.1 Assigning CPUs

You should avoid overcommitting CPUs. Unless you know exactly how many virtual CPUs are required for a VM Guest, you should start with a single virtual CPU per VM Guest. Each virtual CPU should match one hardware processor or core on the VM Host Server.

You should target a CPU workload of approximately 70% inside your VM (see https://www.suse.com/documentation/sles-12/book_sle_tuning/data/sec_util_processes.html for information on monitoring tools). If you allocate more processors than needed in the VM Guest, this will negatively affect the performance of host and guest: cycle efficiency will be degraded, the unused vCPU will consume timer interrupts and will idle-loop. In case you primarily run single threaded applications on a VM Guest, a single virtual CPU is the best choice.

4.5.2 VM Guest CPU Configuration

This section describes how to choose and configure a CPU type for a VM Guest. You will also learn how to pin virtual CPUs to physical CPUs on the host system. For more information about virtual CPU configuration and tuning parameters refer to the libvirt documentation at https://libvirt.org/formatdomain.html#elementsCPU.

4.5.2.1 Virtual CPU Models and Features

The CPU model and topology can be specified individually for each VM Guest. Configuration options range from selecting specific CPU models to excluding certain CPU features. Predefined CPU models are listed in the /usr/share/libvirt/cpu_map.xml. A CPU model and topology that is similar to the host generally provides the best performance. The host system CPU model and topology can be displayed by running virsh capabilities.

Note that changing the default virtual CPU configuration will require a VM Guest shutdown when migrating it to a host with different hardware. More information on VM Guest migration is available at https://www.suse.com/documentation/sles-12/book_virt/data/sec_libvirt_admin_migrate.html.

To specify a particular CPU model for a VM Guest, add a respective entry to the VM Guest configuration file. The following example configures a Broadwell CPU with the invariant TSC feature:

<cpu mode='custom' match='exact'>
  <model>Broadwell</model>
  <feature name='invtsc'/>
  </cpu>

For a virtual CPU that most closely resembles the host physical CPU, <cpu mode='host-passthrough'> can be used. Note that a host-passthrough CPU model may not exactly resemble the host physical CPU, since by default KVM will mask any non-migratable features. For example invtsc is not included in the virtual CPU feature set. Changing the default KVM behavior is not directly supported through libvirt, although it does allow arbitrary passthrough of KVM command line arguments. Continuing with the invtsc example, you can achieve passthrough of the host CPU (including invtsc) by the following command line passthrough in VM Guest configuration file:

<domain type='kvm' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>
     <qemu:commandline>
     <qemu:arg value='-cpu'/>
     <qemu:arg value='host,migratable=off,+invtsc'/>
     </qemu:commandline>
     ...
     </domain>
Note
Note: The host-passthrough Mode

Since host-passthrough exposes the physical CPU details to the virtual CPU, migration to dissimilar hardware is not possible. See Section 4.5.2.3, “Virtual CPU Migration Considerations” for more information.

4.5.2.2 Virtual CPU Pinning

Virtual CPU pinning is used to constrain virtual CPU threads to a set of physical CPUs. The vcpupin element specifies the physical host CPUs that a virtual CPU can use. If this element is not set and the attribute cpuset of the vcpu element is not specified, the virtual CPU is free to use any of the physical CPUs.

CPU intensive workloads can benefit from virtual CPU pinning by increasing the physical CPU cache hit ratio. To pin a virtual CPU to a specific physical CPU, run the following commands:

tux > virsh vcpupin DOMAIN_ID --vcpu vCPU_NUMBER
VCPU: CPU Affinity
----------------------------------
0: 0-7
root # virsh vcpupin SLE12 --vcpu 0 0 --config

The last command generates the following entry in the XML configuration:

<cputune>
   <vcpupin vcpu='0' cpuset='0'/>
</cputune>
Note
Note: Virtual CPU Pinning on NUMA Nodes

To confine a VM Guest's CPUs and its memory to a NUMA node, you can use virtual CPU pinning and memory allocation policies on a NUMA system. See Section 4.6, “NUMA Tuning” for more information related to NUMA tuning.

Warning
Warning: Virtual CPU Pinning and Live Migration

Even though vcpupin can improve performance, it can complicate live migration. See Section 4.5.2.3, “Virtual CPU Migration Considerations” for more information on virtual CPU migration considerations.

4.5.2.3 Virtual CPU Migration Considerations

Selecting a virtual CPU model containing all the latest features may improve performance of a VM Guest workload—but often at the expense of migratability. Unless all hosts in the cluster contain the latest CPU features, migration can fail when a destination host lacks the new features. If migratability of a virtual CPU is preferred over the latest CPU features, a normalized CPU model and feature set should be used. The virsh cpu-baseline command can help define a normalized virtual CPU that can be migrated across all hosts. The following command, when run on each host in the migration cluster, illustrates collection of all hosts' CPU capabilities in all-hosts-cpu-caps.xml.

tux > sudo virsh capabilities | virsh cpu-baseline /dev/stdin >> all-hosts-cpu-caps.xml

With the CPU capabilities from each host collected in all-hosts-cpu-caps.xml, use virsh cpu-baseline to create a virtual CPU definition that will be compatible across all hosts.

tux > sudo virsh cpu-baseline all-hosts-cpu-caps.xml

The resulting virtual CPU definition can be used as the cpu element in VM Guest configuration file.

At a logical level, virtual CPU pinning is a form of hardware passthrough. Pinning couples physical resources to virtual resources, and can also be problematic for migration. For example, the migration will fail if the requested physical resources are not available on the destination host, or if the source and destination hosts have different NUMA topologies. For more recommendations about Live Migration see Virtualization Live Migration Requirements.

4.6 NUMA Tuning

NUMA is an acronym for Non Uniform Memory Access. A NUMA system has multiple physical CPUs, each with local memory attached. Each CPU can also access other CPUs' memory, known as remote memory access, but it is much slower than accessing local memory. NUMA systems can negatively impact VM Guest performance if not tuned properly. Although ultimately tuning is workload dependent, this section describes controls that should be considered when deploying VM Guests on NUMA hosts. Always consider your host topology when configuring and deploying VMs.

SUSE Linux Enterprise Server contains a NUMA auto-balancer that strives to reduce remote memory access by placing memory on the same NUMA node as the CPU processing it. In addition, standard tools such as cgset and virtualization tools such as libvirt provide mechanisms to constrain VM Guest resources to physical resources.

numactl is used to check for host NUMA capabilities:

tux > sudo numactl --hardware
available: 4 nodes (0-3)
node 0 cpus: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 72 73 74 75 76 77 78
79 80 81 82 83 84 85 86 87 88 89
node 0 size: 31975 MB
node 0 free: 31120 MB
node 1 cpus: 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 90 91 92 93
94 95 96 97 98 99 100 101 102 103 104 105 106 107
node 1 size: 32316 MB
node 1 free: 31673 MB
node 2 cpus: 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 108 109 110
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
node 2 size: 32316 MB
node 2 free: 31726 MB
node 3 cpus: 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 126 127 128
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
node 3 size: 32314 MB
node 3 free: 31387 MB
node distances:
node   0   1   2   3
0:  10  21  21  21
1:  21  10  21  21
2:  21  21  10  21
3:  21  21  21  10

The numactl output shows this is a NUMA system with 4 nodes or cells, each containing 36 CPUs and approximately 32G memory. virsh capabilities can also be used to examine the systems NUMA capabilities and CPU topology.

4.6.1 NUMA Balancing

On NUMA machines, there is a performance penalty if remote memory is accessed by a CPU. Automatic NUMA balancing scans a task's address space and unmaps pages. By doing so, it detects whether pages are properly placed or whether to migrate the data to a memory node local to where the task is running. In defined intervals (configured with numa_balancing_scan_delay_ms), the task scans the next scan size number of pages (configured with numa_balancing_scan_size_mb) in its address space. When the end of the address space is reached the scanner restarts from the beginning.

Higher scan rates cause higher system overhead as page faults must be trapped and data needs to be migrated. However, the higher the scan rate, the more quickly a task's memory is migrated to a local node when the workload pattern changes. This minimizes the performance impact because of remote memory accesses. These sysctl directives control the thresholds for scan delays and the number of pages scanned:

tux > sudo sysctl -a | grep numa_balancing
kernel.numa_balancing = 11
kernel.numa_balancing_scan_delay_ms = 10002
kernel.numa_balancing_scan_period_max_ms = 600003
kernel.numa_balancing_scan_period_min_ms = 10004
kernel.numa_balancing_scan_size_mb = 2565

1

Enables/disables automatic page fault-based NUMA balancing

2

Starting scan delay used for a task when it initially forks

3

Maximum time in milliseconds to scan a task's virtual memory

4

Minimum time in milliseconds to scan a task's virtual memory

5

Size in megabytes' worth of pages to be scanned for a given scan

For more information see https://www.suse.com/documentation/sles-12/book_sle_tuning/data/cha_tuning_numactl.html.

The main goal of automatic NUMA balancing is either to reschedule tasks on the same node's memory (so the CPU follows the memory), or to copy the memory's pages to the same node (so the memory follows the CPU).

Warning
Warning: Task Placement

There are no rules to define the best place to run a task, because tasks could share memory with other tasks. For best performance, it is recommended to group tasks sharing memory on the same node. Check NUMA statistics with # cat /proc/vmstat | grep numa_.

4.6.2 Memory Allocation Control with the CPUset Controller

The cgroups cpuset controller can be used confine memory used by a process to a NUMA node. There are three cpuset memory policy modes available:

  • interleave: This is a memory placement policy which is also known as round-robin. This policy can provide substantial improvements for jobs that need to place thread local data on the corresponding node. When the interleave destination is not available, it will be moved to another node.

  • bind: This will place memory only on one node, which means in case of insufficient memory, the allocation will fail.

  • preferred: This policy will apply a preference to allocate memory to a node. If there is not enough space for memory on this node, it will fall back to another node.

You can change the memory policy mode with the cgset tool from the libcgroup-tools package:

tux > sudo cgset -r cpuset.mems=NODE sysdefault/libvirt/qemu/KVM_NAME/emulator

To migrate pages to a node, use the migratepages tool:

tux > migratepages PID FROM-NODE TO-NODE

To check everything is fine. use: cat /proc/PID/status | grep Cpus.

Note
Note: Kernel NUMA/cpuset memory policy

For more information see Kernel NUMA memory policy and cpusets memory policy. Check also the Libvirt NUMA Tuning documentation.

4.6.3 VM Guest: NUMA Related Configuration

libvirt allows to set up virtual NUMA and memory access policies. Configuring these settings is not supported by virt-install or virt-manager and needs to be done manually by editing the VM Guest configuration file with virsh edit.

4.6.3.1 VM Guest Virtual NUMA Topology

Creating a VM Guest virtual NUMA (vNUMA) policy that resembles the host NUMA topology can often increase performance of traditional large, scale-up workloads. VM Guest vNUMA topology can be specified using the numa element in the XML configuration:

<cpu>
...
  <numa>
    <cell1 id='0'2 cpus='0-1'3 memory='512000' unit='KiB'/>
    <cell id='1' cpus='2-3' memory='256000'4
    unit='KiB'5 memAccess='shared'6/>
  </numa>
  ...
</cpu>

1

Each cell element specifies a vNUMA cell or node

2

All cells should have an id attribute, allowing to reference the cell in other configuration blocks. Otherwise cells are assigned ids in ascending order starting from 0.

3

The CPU or range of CPUs that are part of the node

4

The node memory

5

Units in which node memory is specified

6

Optional attribute which can control whether the memory is to be mapped as shared or private. This is valid only for hugepages-backed memory.

To find where the VM Guest has allocated its pages. use: cat /proc/PID/numa_maps and cat /sys/fs/cgroup/memory/sysdefault/libvirt/qemu/KVM_NAME/memory.numa_stat.

Warning
Warning: NUMA specification

The libvirt VM Guest NUMA specification is currently only available for QEMU/KVM.

4.6.3.2 Memory Allocation Control with libvirt

If the VM Guest has a vNUMA topology (see Section 4.6.3.1, “VM Guest Virtual NUMA Topology”), memory can be pinned to host NUMA nodes using the numatune element. This method is currently only available for QEMU/KVM guests. See Important: Non-vNUMA VM Guest for how to configure non-vNUMA VM Guests.

<numatune>
    <memory mode="strict"1 nodeset="1-4,^3"2/>
    <memnode3 cellid="0"4 mode="strict" nodeset="1"/>
    <memnode cellid="2" placement="strict"5 mode="preferred" nodeset="2"/>
</numatune>

1

Policies available are: interleave (round-robin like), strict (default) or preferred.

2

Specify the NUMA nodes.

3

Specify memory allocation policies for each guest NUMA node (if this element is not defined then this will fall back and use the memory element).

4

Addresses the guest NUMA node for which the settings are applied.

5

The placement attribute can be used to indicate the memory placement mode for a domain process, the value can be auto or strict.

Important
Important: Non-vNUMA VM Guest

On a non-vNUMA VM Guest, pinning memory to host NUMA nodes is done like in the following example:

<numatune>
   <memory mode="strict" nodeset="0-1"/>
</numatune>

In this example, memory is allocated from the host nodes 0 and 1. In case these memory requirements cannot be fulfilled, starting the VM Guest will fail. virt-install also supports this configuration with the --numatune option.

Warning
Warning: Memory and CPU across NUMA Nodes

You should avoid allocating VM Guest memory across NUMA nodes, and prevent virtual CPUs from floating across NUMA nodes.

5 VM Guest Images

Images are virtual disks used to store the operating system and data of VM Guests. They can be created, maintained and queried with the qemu-img command. Refer to SLE12 qemu-img documentation for more information on the qemu-img tool and examples.

5.1 VM Guest Image Formats

Certain storage formats which QEMU recognizes have their origins in other virtualization technologies. By recognizing these formats, QEMU can leverage either data stores or entire guests that were originally targeted to run under these other virtualization technologies. Some formats are supported only in read-only mode. To use them in read/write mode, convert them to a fully supported QEMU storage format (using qemu-img). Otherwise they can only be used as read-only data store in a QEMU guest. See SUSE Linux Enterprise Release Notes to get the list of supported formats.

Use qemu-img info VMGUEST.IMG to get information about an existing image, such as: the format, the virtual size, the physical size, snapshots if available.

Note
Note: Performance

It is recommended to convert the disk images to either raw or qcow2 to achieve good performance.

Warning
Warning: Encrypted Images Cannot Be Compressed

When you create an image, you cannot use compression (-c) in the output file together with the encryption option (-e).

5.1.1 Raw Format

  • This format is simple and easily exportable to all other emulators/hypervisors.

  • It provides best performance (least I/O overhead).

  • If your file system supports holes (for example in Ext2 or Ext3 on Linux or NTFS on Windows*), then only the written sectors will reserve space.

  • The raw format allows to copy a VM Guest image to a physical device (dd if=VMGUEST.RAW of=/dev/sda).

  • It is byte-for-byte the same as what the VM Guest sees, so this wastes a lot of space.

5.1.2 qcow2 Format

  • Use this to have smaller images (useful if your file system does not supports holes, for example on Windows*).

  • It has optional AES encryption.

  • Zlib-based compression option.

  • Support of multiple VM snapshots (internal, external).

  • Improved performance and stability.

  • Supports changing the backing file.

  • Supports consistency checks.

  • Less performance than raw format.

l2-cache-size

qcow2 can provide the same performance for random read/write access as raw format, but it needs a well-sized cache size. By default cache size is set to 1 MB. This will give good performance up to a disk size of 8 GB. If you need a bigger disk size, you need to adjust the cache size. For a disk size of 64 GB (64*1024 = 65536), you need 65536 / 8192B = 8 MB of cache (-drive format=qcow2,l2-cache-size=8M).

Cluster Size

The qcow2 format offers the capability to change the cluster size. The value must be between 512 KB and 2 MB. Smaller cluster sizes can improve the image file size whereas larger cluster sizes generally provide better performance.

Preallocation

An image with preallocated metadata is initially larger but can improve performance when the image needs to grow.

Lazy Refcounts

Reference count updates are postponed with the goal of avoiding metadata I/O and improving performance. This is particularly beneficial with cache=writethrough. This option does not batch metadata updates, but if in case of host crash, the reference count tables must be rebuilt, this is done automatically at the next open with qemu-img check -r all. Note that this takes some time.

5.1.3 qed format

qed is the next-generation qcow (QEMU Copy On Write). Its characteristics include:

  • Strong data integrity because of simple design.

  • Retains sparseness over non-sparse channels (for example HTTP).

  • Supports changing the backing file.

  • Supports consistency checks.

  • Fully asynchronous I/O path.

  • Does not support internal snapshots.

  • Relies on the host file system and cannot be stored on a logical volume directly.

5.1.4 VMDK format

VMware 3, 4, or 6 image format, for exchanging images with that product.

5.2 Overlay Disk Images

The qcow2 and qed formats provide a way to create a base image (also called backing file) and overlay images on top of the base image. A backing file is useful to be able to revert to a known state and discard the overlay. If you write to the image, the backing image will be untouched and all changes will be recorded in the overlay image file. The backing file will never be modified unless you use the commit monitor command (or qemu-img commit).

To create an overlay image:

root # qemu-img create -o1backing_file=vmguest.raw2,backing_fmt=raw3\
     -f4 qcow2 vmguest.cow5

1

Use -o ? for an overview of available options.

2

The backing file name.

3

Specify the file format for the backing file.

4

Specify the image format for the VM Guest.

5

Image name of the VM Guest, it will only record the differences from the backing file.

Warning
Warning: Backing Image Path

You should not change the path to the backing image, otherwise you will need to adjust it. The path is stored in the overlay image file. To update the path, you should make a symbolic link from the original path to the new path and then use the qemu-img rebase option.

root # ln -sf /var/lib/images/vmguest.raw  /var/lib/images/SLE12/vmguest.raw
root # qemu-img rebase1-u2 -b3 /var/lib/images/vmguest.raw /var/lib/images/SLE12/vmguest.cow4

The rebase subcommand tells qemu-img to change the backing file image. The -u option activates the unsafe mode (see note below). The backing image to be used is specified with -b and the image path is the last argument of the command.

There are two different modes in which rebase can operate:

  • Safe: This is the default mode and performs a real rebase operation. The safe mode is a time-consuming operation.

  • Unsafe: The unsafe mode (-u) only changes the backing files name and the format of the file name without making any checks on the files contents. You should use this mode to rename or moving a backing file.

A common use is to initiate a new guest with the backing file. Let's assume we have a sle12_base.img VM Guest ready to be used (fresh installation without any modification). This will be our backing file. Now you need to test a new package, on an updated system and on a system with a different kernel. We can use sle12_base.img to instantiate the new SUSE Linux Enterprise VM Guest by creating a qcow2 overlay file pointing to this backing file (sle12_base.img).

In our example we will use sle12_updated.qcow2 for the updated system, and sle12_kernel.qcow2 for the system with a different kernel.

To create the two thin provisioned systems use the qemu-img command line with the -b option:

root # qemu-img create -b /var/lib/libvirt/sle12_base.img -f qcow2 \
/var/lib/libvirt/sle12_updated.qcow2
Formatting 'sle12_updated.qcow2', fmt=qcow2 size=17179869184
backing_file='sle12_base.img' encryption=off cluster_size=65536
lazy_refcounts=off nocow=off
root # qemu-img create -b /var/lib/libvirt/sle12_base.img -f qcow2 \
/var/lib/libvirt/sle12_kernel.qcow2
Formatting 'sle12_kernel.qcow2', fmt=qcow2 size=17179869184
backing_file='vmguest-sle12_base.img' encryption=off cluster_size=65536
lazy_refcounts=off nocow=off

The images are now usable, and you can do your test without touching the initial sle12_base.img backing file, all changes will be stored in the new overlay images. Additionally, you can also use these new images as a backing file, and create a new overlay.

root # qemu-img create -b sle12_kernel.qcow2 -f qcow2 sle12_kernel_TEST.qcow2

When using qemu-img info with the option --backing-chain, it will return all information about the entire backing chain recursively:

root # qemu-img info --backing-chain
/var/lib/libvirt/images/sle12_kernel_TEST.qcow2
image: sle12_kernel_TEST.qcow2
file format: qcow2
virtual size: 16G (17179869184 bytes)
disk size: 196K
cluster_size: 65536
backing file: sle12_kernel.qcow2
Format specific information:
compat: 1.1
lazy refcounts: false

image: sle12_kernel.qcow2
file format: qcow2
virtual size: 16G (17179869184 bytes)
disk size: 196K
cluster_size: 65536
backing file: SLE12.qcow2
Format specific information:
compat: 1.1
lazy refcounts: false

image: sle12_base.img
file format: qcow2
virtual size: 16G (17179869184 bytes)
disk size: 16G
cluster_size: 65536
Format specific information:
compat: 1.1
lazy refcounts: true
Understanding Image Overlay
Figure 1: Understanding Image Overlay

5.3 Opening a VM Guest Image

To access the file system of an image, use the guestfs-tools. If you do not have this tool installed on your system you can mount an image with other Linux tools. Avoid accessing an untrusted or unknown VM Guest's image system because this can lead to security issues (for more information, read D. Berrangé's post).

5.3.1 Opening a Raw Image

Procedure 5: Mounting a Raw Image
  1. To be able to mount the image, find a free loop device. The following command displays the first unused loop device, /dev/loop1 in this example.

    root # losetup -f
    /dev/loop1
  2. Associate an image (SLE12.raw in this example) with the loop device:

    root # losetup /dev/loop1 SLE12.raw
  3. Check whether the image has successfully been associated with the loop device by getting detailed information about the loop device:

    root # losetup -l
    NAME       SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE
    /dev/loop1         0      0         0  0    /var/lib/libvirt/images/SLE12.raw
  4. Check the image's partitions with kpartx:

    root # kpartx -a1 -v2 /dev/loop1
    add map loop1p1 (254:1): 0 29358080 linear /dev/loop1 2048

    1

    Add partition device mappings.

    2

    Verbose mode.

  5. Now mount the image partition(s) (to /mnt/sle12mount in the following example):

    root # mkdir /mnt/sle12mount
    root # mount /dev/mapper/loop1p1 /mnt/sle12mount
Note
Note: Raw image with LVM

If your raw image contains an LVM volume group you should use LVM tools to mount the partition. Refer to Section 5.3.3, “Opening Images Containing LVM”.

Procedure 6: Unmounting a Raw Image
  1. Unmount all mounted partitions of the image, for example:

    root # umount /mnt/sle12mount
  2. Delete partition device mappings with kpartx:

    root # kpartx -d /dev/loop1
  3. Detach the devices with losetup

    root # losetup -d /dev/loop1

5.3.2 Opening a qcow2 Image

Procedure 7: Mounting a qcow2 Image
  1. First you need to load the nbd (network block devices) module. The following example loads it with support for 16 block devices (max_part=16). Check with dmesg whether the operation was successful:

    root # modprobe nbd max_part=16
    root # dmesg | grep nbd
    [89155.142425] nbd: registered device at major 43
  2. Connect the VM Guest image (for example SLE12.qcow2) to an NBD device (/debv/nbd0 in the following example) with the qemu-nbd command. Make sure to use a free NBD device:

    root # qemu-nbd -c1 /dev/nbd02 SLE12.qcow23

    1

    Connect SLE12.qcow2 to the local NBD device /dev/nbd0

    2

    NBD device to use

    3

    VM Guest image to use

    Tip
    Tip: Checking for a free NBD Device

    To check whether an NBD device is free, run the following command:

    root # lsof /dev/nbd0
    COMMAND    PID USER   FD   TYPE DEVICE SIZE/OFF  NODE NAME
    qemu-nbd 15149 root   10u   BLK   43,0      0t0 47347 /dev/nbd0

    If the command produces an output like in the example above, the device is busy (not free). This can also be confirmed by the presence of the /sys/devices/virtual/block/nbd0/pid file.

  3. Inform the operating system about partition table changes with partprobe:

    root # partprobe /dev/nbd0 -s
    /dev/nbd0: msdos partitions 1 2
    root # dmesg | grep nbd0 | tail -1
    [89699.082206]  nbd0: p1 p2
  4. In the example above, the SLE12.qcow2 contains two partitions: /dev/nbd0p1 and /dev/nbd0p2. Before mounting these partitions, use vgscan to check whether they belong to an LVM volume:

    root # vgscan -v
        Wiping cache of LVM-capable devices
        Wiping internal VG cache
        Reading all physical volumes. This may take a while...
        Using volume group(s) on command line.
        No volume groups found.
  5. If no LVM volume has been found, you can mount the partition with mount:

    root # mkdir /mnt/nbd0p2
    # mount /dev/nbd0p1 /mnt/nbd0p2

    Refer to Section 5.3.3, “Opening Images Containing LVM” for information on how to handle LVM volumes.

Procedure 8: Unmounting a qcow2 Image
  1. Unmount all mounted partitions of the image, for example:

    root # umount /mnt/nbd0p2
  2. Disconnect the image from the /dev/nbd0 device.

    root # qemu-nbd -d /dev/nbd0

5.3.3 Opening Images Containing LVM

Procedure 9: Mounting Images Containing LVM
  1. To check images for LVM groups, use vgscan -v. If an image contains LVM groups, the output of the command looks like the following:

    root # vgscan -v
    Wiping cache of LVM-capable devices
    Wiping internal VG cache
    Reading all physical volumes.  This may take a while...
    Finding all volume groups
    Finding volume group "system"
    Found volume group "system" using metadata type lvm2
  2. The system LVM volume group has been found on the system. You can get more information about this volume with vgdisplay VOLUMEGROUPNAME (in our case VOLUMEGROUPNAME is system). You should activate this volume group to expose LVM partitions as devices so the system can mount them. Use vgchange:

    root # vgchange -ay -v
    Finding all volume groups
    Finding volume group "system"
    Found volume group "system"
    activation/volume_list configuration setting not defined: Checking only
    host tags for system/home
    Creating system-home
    Loading system-home table (254:0)
    Resuming system-home (254:0)
    Found volume group "system"
    activation/volume_list configuration setting not defined: Checking only
    host tags for system/root
    Creating system-root
    Loading system-root table (254:1)
    Resuming system-root (254:1)
    Found volume group "system"
    activation/volume_list configuration setting not defined: Checking only
    host tags for system/swap
    Creating system-swap
    Loading system-swap table (254:2)
    Resuming system-swap (254:2)
    Activated 3 logical volumes in volume group system
        3 logical volume(s) in volume group "system" now active
  3. All partitions in the volume group will be listed in the /dev/mapper directory. You can simply mount them now.

    root # ls /dev/mapper/system-*
    /dev/mapper/system-home  /dev/mapper/system-root /dev/mapper/system-swap
    
    root # mkdir /mnt/system-root
    root # mount  /dev/mapper/system-root /mnt/system-root
    
    root # ls /mnt/system-root/
    bin   dev  home  lib64       mnt  proc        root  sbin     srv  tmp  var
    boot  etc  lib   lost+found  opt  read-write  run   selinux  sys  usr
Procedure 10: Unmounting Images Containing LVM
  1. Unmount all partitions (with umount)

    root # umount /mnt/system-root
  2. Deactivate the LVM volume group (with vgchange -an VOLUMEGROUPNAME)

    root # vgchange -an -v system
    Using volume group(s) on command line
    Finding volume group "system"
    Found volume group "system"
    Removing system-home (254:0)
    Found volume group "system"
    Removing system-root (254:1)
    Found volume group "system"
    Removing system-swap (254:2)
    Deactivated 3 logical volumes in volume group system
    0 logical volume(s) in volume group "system" now active
  3. Now you have two choices:

    • In case of a qcow2 image, proceed as described in Step 2 (qemu-nbd -d /dev/nbd0).

    • In case of a raw image, proceeds as described in Step 2 (kpartx -d /dev/loop1; losetup -d /dev/loop1).

    Important
    Important: Check for a Successful Unmount

    You should double-check that umounting succeeded by using a system command like losetup, qemu-nbd, mount or vgscan. If this is not the case you may have trouble using the VM Guest because its system image is used in different places.

5.4 File System Sharing

You can access a host directory in the VM Guest using the filesystem element. In the following example we will share the /data/shared directory and mount it in the VM Guest. Note that the accessmode parameter only works with type='mount' for the QEMU/KVM drive (most other values for type are exclusively used for the LXC driver).

<filesystem type='mount'1 accessmode='mapped'2>
   <source dir='/data/shared'3>
   <target dir='shared'4/>
</filesystem>

1

A host directory to mount VM Guest.

2

Access mode (the security mode) set to mapped will give access with the permissions of the hypervisor. Use passthrough to access this share with the permissions of the user inside the VM Guest.

3

Path to share with the VM Guest.

4

Name or label of the path for the mount command.

To mount the shared directory on the VM Guest, use the following commands: Under the VM Guest now you need to mount the target dir='shared':

root # mkdir /opt/mnt_shared
root # mount shared -t 9p /opt/mnt_shared -o trans=virtio

See libvirt File System and QEMU 9psetup for more information.

6 VM Guest Configuration

6.1 Virtio Driver

To increase VM Guest performance it is recommended to use paravirtualized drivers within the VM Guests. The virtualization standard for such drivers for KVM are the virtio drivers, which are designed for running in a virtual environment. Xen uses similar paravirtualized device drivers (like VMDP in a Windows* guest). For a better understanding of this topic, refer to the I/O Virtualization section in the official Virtualization Guide.

6.1.1 virtio blk

virtio_blk is the virtio block device for disk. To use the virtio blk driver for a block device, specify the bus='virtio' attribute in the disk definition:

<disk type='....' device='disk'>
    ....
    <target dev='vda' bus='virtio'/>
</disk>
Important
Important: Disk Device Names

virtio disk devices are named /dev/vd[a-z][1-9]. If you migrate a Linux guest from a non-virtio disk you need to adjust the root= parameter in the GRUB configuration, and regenerate the initrd file. Otherwise the system cannot boot. On VM Guests with other operating systems, the boot loader may need to be adjusted or reinstalled accordingly, too.

Important
Important: Using virtio Disks with qemu-system-ARCH

When running qemu-system-ARCH, use the -drive option to add a disk to the VM Guest. See the Basic Installation with qemu-system-ARCH section in the official Virtualization guide for an example. The -hd[abcd] option will not work for virtio disks.

6.1.2 virtio net

virtio_net is the virtio network device. The kernel modules should be loaded automatically in the guest at boot time. You need to start the service to make the network available.

<interface type='network'>
    ...
    <model type='virtio' />
</interface>

6.1.3 virtio balloon

The virtio balloon is used for host memory over-commits for guests. For Linux guests, the balloon driver runs in the guest kernel, whereas for Windows guests, the balloon driver is in the VMDP package. virtio_balloon is a PV driver to give or take memory from a VM Guest.

  • Inflate balloon: Return memory from guest to host kernel (for KVM) or to hypervisor (for Xen)

  • Deflate balloon: Guest will have more available memory

It is controlled by the currentMemory and memory options.

<memory unit='KiB'>16777216</memory>
    <currentMemory unit='KiB'>1048576</currentMemory>
    [...]
    <devices>
        <memballoon model='virtio'/>
    </devices>

You can also use virsh to change it:

tux > virsh setmem DOMAIN_ID MEMORY in KB

6.1.4 Checking virtio Presence

You can check the virtio block PCI with:

tux > find /sys/devices/ -name virtio*
/sys/devices/pci0000:00/0000:00:06.0/virtio0
/sys/devices/pci0000:00/0000:00:07.0/virtio1
/sys/devices/pci0000:00/0000:00:08.0/virtio2

To find the block device associated with vdX:

tux > find /sys/devices/ -name virtio* -print  -exec ls {}/block 2>/dev/null \;
/sys/devices/pci0000:00/0000:00:06.0/virtio0
/sys/devices/pci0000:00/0000:00:07.0/virtio1
/sys/devices/pci0000:00/0000:00:08.0/virtio2
vda

To get more information on the virtio block:

tux > udevadm info -p /sys/devices/pci0000:00/0000:00:08.0/virtio2
P: /devices/pci0000:00/0000:00:08.0/virtio2
E: DEVPATH=/devices/pci0000:00/0000:00:08.0/virtio2
E: DRIVER=virtio_blk
E: MODALIAS=virtio:d00000002v00001AF4
E: SUBSYSTEM=virtio

To check all virtio drivers being used:

tux > find /sys/devices/ -name virtio* -print  -exec ls -l {}/driver 2>/dev/null \;
/sys/devices/pci0000:00/0000:00:06.0/virtio0
lrwxrwxrwx 1 root root 0 Jun 17 15:48 /sys/devices/pci0000:00/0000:00:06.0/virtio0/driver -> ../../../../bus/virtio/drivers/virtio_console
/sys/devices/pci0000:00/0000:00:07.0/virtio1
lrwxrwxrwx 1 root root 0 Jun 17 15:47 /sys/devices/pci0000:00/0000:00:07.0/virtio1/driver -> ../../../../bus/virtio/drivers/virtio_balloon
/sys/devices/pci0000:00/0000:00:08.0/virtio2
lrwxrwxrwx 1 root root 0 Jun 17 14:35 /sys/devices/pci0000:00/0000:00:08.0/virtio2/driver -> ../../../../bus/virtio/drivers/virtio_blk

6.1.5 Find Device Driver Options

Virtio devices and other drivers have various options. To list all of them, use the help parameter of theqemu-system-ARCH command.

tux > qemu-system-x86_64 -device virtio-net,help
virtio-net-pci.ioeventfd=on/off
virtio-net-pci.vectors=uint32
virtio-net-pci.indirect_desc=on/off
virtio-net-pci.event_idx=on/off
virtio-net-pci.any_layout=on/off
.....

6.2 Cirrus Video Driver

To get 16-bit color, high compatibility and better performance it is recommended to use the cirrus video driver.

Note
Note: libvirt

libvirt ignores the vram value because video size has been hardcoded in QEMU.

<video>
   <model type='cirrus' vram='9216' heads='1'/>
</video>

6.3 Better Entropy

Virtio RNG (random number generator) is a paravirtualized device that is exposed as a hardware RNG device to the guest. On the host side, it can be wired up to one of several sources of entropy (including a real hardware RNG device and the host's /dev/random) if hardware support does not exist. The Linux kernel contains the guest driver for the device from version 2.6.26 and higher.

The system entropy is collected from various non-deterministic hardware events and is mainly used by cryptographic applications. The virtual random number generator device (paravirtualized device) allows the host to pass through entropy to VM Guest operating systems. This results in a better entropy in the VM Guest.

To use Virtio RNG, add an RNG device in virt-manager or directly in the VM Guest's XML configuration:

<devices>
   <rng model='virtio'>
       <backend model='random'>/dev/random</backend>
   </rng>
</devices>

The host now should used /dev/random:

tux > lsof /dev/random
qemu-syst 4926 qemu    6r   CHR    1,8      0t0 8199 /dev/random

On the VM Guest, the source of entropy can be checked with:

tux > cat /sys/devices/virtual/misc/hw_random/rng_available

The current device used for entropy can be checked with:

tux > cat /sys/devices/virtual/misc/hw_random/rng_current
virtio_rng.0

You should install the rng-tools package on the VM Guest, enable the service, and start it. Under SLE12 do the following:

root # zypper in rng-tools
root # systemctl enable rng-tools
root # systemctl start rng-tools

6.4 Disable Unused Tools and Devices

Per host, use one virtualization technology only. For example, do not use KVM and Containers on the same computer. Otherwise, you may find yourself with a reduced amount of available resources, increased security risk and a longer software update queue. Even when the amount of resources allocated to each of the technologies is configured carefully, the host may suffer from reduced overall availability and degraded performance.

Minimize the amount of software and services available on hosts. Most default installations of operating systems are not optimized for VM usage. Install what you really need and remove all other components in the VM Guest.

Windows* Guest:

  • Disable the screen saver

  • Remove all graphical effects

  • Disable indexing of hard disks if not necessary

  • Check the list of started services and disable the ones you do not need

  • Check and remove all unneeded devices

  • Disable system update if not needed, or configure it to avoid any delay while rebooting or shutting down the host

  • Check the Firewall rules

  • Schedule backups and anti-virus updates appropriately

  • Install the VMDP paravirtualized driver for best performance

  • Check the operating system recommendations, such as on the Microsoft Windows* 7 better performance Web page.

Linux Guest:

  • Remove or do not start the X Window System if not necessary

  • Check the list of started services and disable the ones you do not need

  • Check the OS recommendations for kernel parameters that enable better performance

  • Only install software that you really need

  • Optimize the scheduling of predictable tasks (system updates, hard disk checks, etc.)

6.5 Updating the Guest Machine Type

QEMU machine types define details of the architecture that are particularly relevant for migration and session management. As changes or improvements to QEMU are made, new machine types are added. Old machine types are still supported for compatibility reasons, but to take advantage of improvements, we recommend to always migrate to the latest machine type when upgrading.

Changing the guest's machine type for a Linux guest will mostly be transparent. For Windows* guests, we recommend to take a snapshot or backup of the guest—in case Windows* has issues with the changes it detects and subsequently the user decides to revert to the original machine type the guest was created with.

Note
Note: Changing the machine type

Refer to the Virtualization guide section Change Machine Type for documentation.

7 VM Guest-Specific Configurations and Settings

7.1 ACPI Testing

The ability to change a VM Guest's state heavily depends on the operating system. It is very important to test this feature before any use of your VM Guests in production. For example, most Linux operating systems disable this capability by default, so this requires you to enable this operation (mostly through PolKit).

ACPI must be enabled in the guest for a graceful shutdown to work. To check if ACPI is enabled, run:

tux > virsh dumpxml VMNAME | grep acpi

If nothing is printed, ACPI is not enabled for your machine. Use virsh edit to add the following XML under <domain>:

<features>
   <acpi/>
</features>

If ACPI was enabled during a Windows Server* guest installation, it is not sufficient to turn it on in the VM Guest configuration only. For more information, see https://support.microsoft.com/en-us/kb/309283.

Regardless of the VM Guest's configuration, a graceful shutdown is always possible from within the guest operating system.

7.2 Keyboard Layout

Though it is possible to specify the keyboard layout from a qemu-system-ARCH command, it is recommended to configure it in the libvirt XML file. To change the keyboard layout while connecting to a remote VM Guest using vnc, you should edit the VM Guest XML configuration file. For example, to add an en-us keymap, add in the <devices> section:

<graphics type='vnc' port='-1' autoport='yes' keymap='en-us'/>

Check the vncdisplay configuration and connect to your VM Guest:

tux > virsh vncdisplay sles12 127.0.0.1:0

7.3 Spice default listen URL

If no network interface other than lo is assigned an IPv4 address on the host, the default address on which the spice server listens will not work. An error like the following one will occur:

tux > virsh start sles12
error: Failed to start domain sles12
error: internal error: process exited while connecting to monitor: ((null):26929): Spice-Warning **: reds.c:2330:reds_init_socket: getaddrinfo(127.0.0.1,5900): Address family for hostname not supported
2015-08-12T11:21:14.221634Z qemu-system-x86_64: failed to initialize spice server

To fix this, you can change the default spice_listen value in /etc/libvirt/qemu.conf using the local IPv6 address ::1. The spice server listening address can also be changed on a per VM Guest basis, use virsh edit to add the listen XML attribute to the graphics type='spice' element:

<graphics type='spice' listen='::1' autoport='yes'/>>

7.4 XML to QEMU command line

Sometimes it could be useful to get the QEMU command line to launch the VM Guest from the XML file.

tux > virsh domxml-to-native1 qemu-argv2 SLE12.xml3

1

Convert the XML file in domain XML format to the native guest configuration

2

For the QEMU/KVM hypervisor, the format argument needs be qemu-argv

3

Domain XML file to use

tux > sudo virsh domxml-to-native qemu-argv /etc/libvirt/qemu/SLE12.xml
LC_ALL=C PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
   QEMU_AUDIO_DRV=none /usr/bin/qemu-system-x86_64 -name SLE12 -machine \
   pc-i440fx-2.3,accel=kvm,usb=off -cpu SandyBridge -m 4048 -realtime \
   mlock=off -smp 4,sockets=4,cores=1,threads=1 -uuid 8616d00f-5f05-4244-97cc-86aeaed8aea7 \
   -no-user-config -nodefaults -chardev socket,id=charmonitor,path=/var/lib/libvirt/qemu/SLE12.monitor,server,nowait \
   -mon chardev=charmonitor,id=monitor,mode=control -rtc base=utc,driftfix=slew \
   -global kvm-pit.lost_tick_policy=discard -no-hpet \
   -no-shutdown -global PIIX4_PM.disable_s3=1 -global PIIX4_PM.disable_s4=1 \
   -boot strict=on -device ich9-usb-ehci1,id=usb,bus=pci.0,addr=0x4.0x7 \
   -device ich9-usb-uhci1,masterbus=usb.0,firstport=0,bus=pci.0,multifunction=on,addr=0x4 \
   -device ich9-usb-uhci2,masterbus=usb.0,firstport=2,bus=pci.0,addr=0x4.0x1 \
   -device ich9-usb-uhci3,masterbus=usb.0,firstport=4,bus=pci.0,addr=0x4.0x2 \
   -drive file=/var/lib/libvirt/images/SLE12.qcow2,if=none,id=drive-virtio-disk0,format=qcow2,cache=none \
   -device virtio-blk-pci,scsi=off,bus=pci.0,addr=0x6,drive=drive-virtio-disk0,id=virtio-disk0,bootindex=2 \
   -drive if=none,id=drive-ide0-0-1,readonly=on,format=raw  \
   -device ide-cd,bus=ide.0,unit=1,drive=drive-ide0-0-1,id=ide0-0-1 -netdev tap,id=hostnet0  \
   -device virtio-net-pci,netdev=hostnet0,id=net0,mac=52:54:00:28:04:a9,bus=pci.0,addr=0x3,bootindex=1 \
   -chardev pty,id=charserial0 -device isa-serial,chardev=charserial0,id=serial0 \
   -vnc 127.0.0.1:0 -device cirrus-vga,id=video0,bus=pci.0,addr=0x2 \
   -device virtio-balloon-pci,id=balloon0,bus=pci.0,addr=0x5 -msg timestamp=on

7.5 Change Kernel Parameters at Boot Time

7.5.1 SUSE Linux Enterprise 11

To change the value for SLE 11 products at boot time, you need to modify your /boot/grub/menu.lst file by adding the OPTION=parameter. Then reboot your system.

7.5.2 SUSE Linux Enterprise 12

To change the value for SLE 12 products at boot time, you need to modify your /etc/default/grub file. Find the variable starting with GRUB_CMDLINE_LINUX_DEFAULT and add at the end OPTION=parameter (or change it with the correct value if it is already available).

Now you need to regenerate your grub2 configuration:

# grub2-mkconfig -o /boot/grub2/grub.cfg

Then reboot your system

7.6 Add a Device to an XML Configuration

To create a new VM Guest based on an XML file, you can specify the QEMU command line using the special tag qemu:commandline. For example, to add a virtio-balloon-pci, add this block at the end of the XML configuration file (before the </domain> tag):

<qemu:commandline>
    <qemu:arg value='-device'/>
    <qemu:arg value='virtio-balloon-pci,id=balloon0'/>
</qemu:commandline>

8 Hypervisors Compared to Containers

Table 4: Hypervisors Compared to Containers

Features

Hypervisors

Containers

Technologies

Emulation of a physical computing environment

Use kernel host

System layer level

Managed by a virtualization layer (Hypervisor)

Rely on kernel namespaces and cgroups

Level (layer)

Hardware level

Software level

Virtualization mode available

FV or PV

None, only user space

Security

Strong

Warning
Warning

Security is very low

Confinement

Full isolation

Warning
Warning

Host kernel (OS must be compatible with kernel version)

Operating system

Any operating system

Only Linux (must be "kernel" compatible)

Type of system

Full OS needed

Scope is an instance of Linux

Boot time

Slow to start (OS delay)

Really quick start

Overhead

High

Very low

Efficiency

Depends on OS

Very efficient

Sharing with host

Warning
Warning

Complex because of isolation

Sharing is easy (host sees everything; container sees its own objects)

Migration

Supports migration (live mode)

Warning
Warning

Not possible

8.1 Getting the Best of Both Worlds

Even if the above table seems to indicate that running a single application in a highly secure way is not possible, virt-sandbox will allow running a single application in a KVM guest, starting with SUSE Linux Enterprise Server 12 SP1. virt-sandbox bootstraps any command within a Linux kernel with a minimal root file system.

The guest root file system can either be the root file system mounted read-only or a disk image. The following steps will show how to set up a sandbox with qcow2 disk image as root file system.

  1. Create the disk image using qemu-img:

    root # qemu-img create -f qcow2 rootfs.qcow2 6G
  2. Format the disk image:

    root # modprobe nbd1
    root # /usr/bin/qemu-nbd --format qcow2 -n -c /dev/nbd0 $PWD/test-base.qcow22
    root # mkfs.ext3 /dev/nbd03

    1

    Make sure the nbd module is loaded: it is not loaded by default and will only be used to format the qcow image.

    2

    Create an NBD device for the qcow2 image. This device will then behave like any other block device. The example uses /dev/nbd0 but any other free NBD device will work.

    3

    Format the disk image directly. Note that no partition table has been created: virt-sandbox considers the image to be a partition, not a disk.

    The partition formats that can be used are limited: the Linux kernel bootstrapping the sandbox needs to have the corresponding features built in. The Ext4 module is also available at the sandbox start-up time.

  3. Now populate the newly formatted image:

    root # guestmount -a base.qcow2 -m /dev/sda:/ /mnt1
    
    root # zypper --root /mnt ar cd:///?devices=/dev/dvd SLES12_DVD
    root # zypper --root /mnt in -t pattern Minimal2
    
    root # guestunmount /mnt3

    1

    Mount the qcow2 image using the guestfs tools.

    2

    Use Zypper with the --root parameter to add a SUSE Linux Enterprise Server repository and install the Minimal pattern in the disk image. Any additional package or configuration change should be performed in this step.

    Note
    Note: Using backing chains

    To share the root file system between several sandboxes, create qcow2 images with a common disk image as backing chain as described in Section 5.2, “Overlay Disk Images”.

    3

    Unmount the qcow2 image.

  4. Run the sandbox, using virt-sandbox. This command has many interesting options, read its man page to discover them all. The command can be run as root or as an unprivileged user.

    root # virt-sandbox -n NAME \
         -m host-image:/=$PWD/rootfs.qcow2 \ 1
         -m host-bind:/srv/www=/guests/www \ 2
         -m ram:/tmp=100MiB \
         -m ram:/run=100MiB \ 3
         -N source=default,address=192.168.122.12/24 \ 4
         -- \
         /bin/sh

    1

    Mount the created disk image as the root file system. Note that without any image being mounted as /, the host root file system is read-only mounted as the guest one.

    The host-image mount is not reserved for the root file system, it can be used to mount any disk image anywhere in the guest.

    2

    The host-bind mount is pretty convenient for sharing files and directories between the host and the guest. In this example the host directory /guests/www is mounted as /srv/www in the sandbox.

    3

    The RAM mounts are defining tmpfs mounts in the sandbox.

    4

    The network uses a network defined in libvirt. When running as an unprivileged user, the source can be omitted, and the KVM user networking feature will be used. Using this option requires the dhcp-client and iproute2 packages, which are part of the SUSE Linux Enterprise Server Minimal pattern.

9 Xen: Converting a Paravirtual (PV) Guest to a Fully Virtual (FV/HVM) Guest

This chapter explains how to convert a Xen paravirtual machine into a Xen fully virtualized machine.

Procedure 11: Guest Side

In order to start the guest in FV mode, you have to run the following steps inside the guest.

  1. Prior to converting the guest, apply all pending patches and reboot the guest.

  2. FV machines use the -default kernel. If this kernel is not already installed, install the kernel-default package (while running in PV mode).

  3. PV machines typically use disk names such as vda*. These names must be changed to the FV hd* syntax. This change must be done in the following files:

    • /etc/fstab

    • /boot/grub/menu.lst (SLES11 only)

    • /boot/grub*/device.map

    • /etc/sysconfig/bootloader

    • /etc/default/grub (SLES12 only)

    Note
    Note: Prefer UUIDs

    You should use UUIDs or logical volumes within your /etc/fstab. Using UUID simplifies using attached network storage, multipathing, and virtualization. To find the UUID of your disk use the command blkid.

  4. To avoid any error regenerating the initrd with the needed modules you can create a symlink from /dev/hda2 to /dev/xvda2 etc. by using the ln:

    ln -sf /dev/xvda2 /dev/hda2
    ln -sf /dev/xvda1 /dev/hda1
    .....
  5. PV and FV machines use different disk and network driver modules. These FV modules must be added to the initrd manually. The expected modules are xen-vbd (for disk) and xen-vnif (for network). These are the only PV drivers for a fully virtualized VM Guest. All other modules, such as ata_piix, ata_generic and libata, should be added automatically.

    Tip
    Tip: Adding Modules to the initrd
    • On SLES 11, you can add modules to the INITRD_MODULES line in the /etc/sysconfig/kernel file. For example:

      INITRD_MODULES="xen-vbd xen-vnif"

      Run mkinitrd to build a new initrd containing the modules.

    • On SLES 12, open or create /etc/dracut.conf.d/01-dist.conf and add the modules with force_drivers by adding a line as in the example below:

      force_drivers+="xen-vbd xen-vnif"

      Run dracut -f --kver [KERNEL_VERSION]-default to build a new initrd (for the -default version of the kernel) which contains the required modules.

      Note
      Note: Find your Kernel version

      Use the uname -r command to get the current version used on your system.

  6. Before shutting down the guest, set the default boot option to the -default kernel using yast bootloader.

  7. Under SUSE Linux Enterprise Server 11, if you have an X server running on your guest, you need to adjust the /etc/X11/xorg.conf file to adjust the X driver. Search for fbdev and change to cirrus.

    Section "Device"
              Driver       "cirrus"
              ......
              EndSection
    Note
    Note: SUSE Linux Enterprise Server 12 and Xorg

    Under SUSE Linux Enterprise Server 12, Xorg will automatically adjust the driver needed to be able to get a working X server.

  8. Shut down the guest.

Procedure 12: Host Side

The following steps explain the action you have to do on the host.

  1. To start the guest in FV mode, the configuration of the VM must be modified to match an FV configuration. Editing the configuration of the VM can easily be done using virsh edit [DOMAIN]. The following changes are recommended:

    • Make sure the machine, the type and the loader entries in the OS section are changed from xenpv to xenfv. The updated OS section should look similar to:

      <os>
                <type arch='x86_64' machine='xenfv'>hvm</type>
                <loader>/usr/lib/xen/boot/hvmloader</loader>
                <boot dev='hd'/>
      </os>
    • In the OS section remove anything which is specific to PV guest:

      • <bootloader>pygrub</bootloader>
      • <kernel>/usr/lib/grub2/x86_64-xen/grub.xen</kernel>
      • <cmdline>xen-fbfront.video=4,1024,768</cmdline>
    • In the devices section, add the qemu emulator as:

      <emulator>/usr/lib/xen/bin/qemu-system-i386</emulator>
    • Update the disk configuration so the target device and bus use the FV syntax. This requires replacing the xen disk bus with ide, and the vda target device with hda. The changes should look similar to:

      <target dev='hda' bus='ide'/>
    • Change the bus for the mouse and keyboard from xen to ps2. Also add a new USB tablet device:

      <input type='mouse' bus='ps2'/>
                <input type='keyboard' bus='ps2'/>
      <input type='tablet' bus='usb'/>
    • Change the console target type from xen to serial:

      <console type='pty'>
                <target type='serial' port='0'/>
      </console>
    • Change the video configuration from xen to cirrus, with 8M of VRAM:

      <video>
                <model type='cirrus' vram='8192' heads='1' primary='yes'/>
      </video>
    • If desired, add acpi and apic to the features of the VM:

      <features>
                <acpi/>
                <apic/>
      </features>
  2. Start the guest (using virsh or virt-manager). If the guest is running kernel-default (as verified through uname -a), the machine is running in Fully Virtual mode.

Note
Note: guestfs-tools

To script this process, or work on disk images directly, you can use the guestfs-tools suite. Numerous tools exist there to help modify disk images.

Print this page